216digital.
Web Accessibility

Phase 1
Web Remediation for Lawsuit Settlement & Prevention


Phase 2
Real-World Accessibility


a11y.Radar
Ongoing Monitoring and Maintenance


Consultation & Training

Is Your Website Vulnerable to Frivolous Lawsuits?
Get a Free Web Accessibility Audit to Learn Where You Stand
Find Out Today!

Web Design & Development

Marketing

PPC Management
Google & Social Media Ads


Professional SEO
Increase Organic Search Strength

Interested in Marketing?
Speak to an Expert about marketing opportunities for your brand to cultivate support and growth online.
Contact Us

About

Blog

Contact Us
  • How to Use aria-describedby for Web Accessibility

    Have you ever looked at a form, seen the bold text or red borders, and instantly known what to do next? That’s because as visual users, we get a lot of clues from layout, color, and spacing. But for someone using a screen reader, those visual hints don’t exist. Instead, they rely on code—programmatic clues—to make sense of what’s on the screen.

    That’s where aria-describedby comes in. If you’ve ever struggled to make a form, button, or modal accessible, you’re not alone. aria-describedby is a powerful tool that helps users understand what’s happening—if you use it right.

    In this article, I’ll walk you through how to use aria-describedby the right way. We’ll go through practical code examples, real use cases, and common mistakes. I’ll also show you how it ties into making things like captions and subtitles more accessible, especially for users with assistive technology.

    Unpacking aria-describedby

    aria-describedby lets you link an element to other content that gives extra detail. It points to the ID(s) of one or more elements that contain helpful text. Think of it like this:

    • aria-labelledby gives something its name.
    • aria-describedby gives it extra explanation.

    If a screen reader sees an input with aria-describedby= "pw-hint", it will read the input label and the hint.

    Why It’s Important

    Used correctly, aria-describedby helps you meet the Web Content Accessibility Guidelines (WCAG) success criteria. It improves accessibility for users who rely on screen readers. It’s especially helpful when native HTML doesn’t cover all the information a user needs. This matters for users navigating complex interfaces—like forms, modals, or media players with captions and subtitles.

    When Should You Use aria-describedby?

    • Form fields: Add help text or error messages.
    • Buttons: Clarify what will happen, especially for destructive actions.
    • Dialogs/modals: Explain what the dialog is for.
    • Tooltips: Offer extra information without cluttering the interface.
    • Live status updates: Let users know when things change, like upload progress or loading indicators.

    aria-describedby can even support captions and subtitles in video players by giving extra context for the screen reader user, describing what’s happening beyond the visual content.

    When Not to Use It

    • If HTML already does the job (like using <label> or <fieldset>).
    • If it adds repetitive or unnecessary text.

    Code Walkthroughs: Real-World Examples

    Let’s get into some code. These examples show how to use aria-describedby in ways that make a real difference.

    Form Fields

    Password Requirements

    <label for="pw">Password</label>
    <input type="password" id="pw" aria-describedby="pw-hint">
    <p id= "pw-hint">Password must be at least 12 characters long and include a number.</p>

    Error Messages

    <label for="email">Email address</label>
    <input type="email" id="email" aria-invalid="true" aria-describedby="email-error">
    <p id="email-error" class="error">Please enter a valid email address.</p>

    Multiple Descriptions

    <input type="text" id="username" aria-describedby="username-req username-tip">
    <p id="username-req">Must be at least 8 characters.</p>
    <p id="username-tip">Displayed on your profile.</p>

    Buttons

    Destructive Action Explanation

    <button aria-describedby="delete-desc">Delete Account</button>
    <p id= "delete-desc">This will permanently remove your account and all data.</p>

    Dialogs and Modals

    Accessible Dialog

    <div role="dialog" aria-modal="true" aria-labelledby="dialogTitle" aria-describedby="dialogDesc">
      <h2 id="dialogTitle">Confirm Deletion</h2>
      <p id= "dialogDesc">This action is permanent and cannot be undone.</p>
    </div>

    Tooltips and Live Regions

    Accessible Tooltip

    <input type="text" id="first" aria-describedby="tip1">
    <div id="tip1" role="tooltip">Optional field.</div>

    Status Messages

    <div aria-describedby="upload-status">
      <input type="file" onchange="showUploadStatus()">
      <div id="upload-status" aria-live="polite">Uploading...</div>
    </div>

    These techniques can also apply to custom media players. You can use aria-describedby to point to captions and subtitles that are visible on screen but also need to be announced programmatically.

    Common Mistakes to Avoid

    • Too Many Descriptions: Linking to 3 or 4 IDs might overwhelm users.
    • Broken References: Make sure every ID you point to actually exists.
    • Redundant Content: Don’t repeat what’s already in the label.
    • Timing Issues: Don’t change the text dynamically during focus unless absolutely necessary.
    • Inconsistent Patterns: Keep your approach consistent across similar components.

    Best Practices for Effective Implementation

    • Write Clear Descriptions: Keep them short, useful, and easy to understand.
    • Avoid Jargon: Explain things in plain language.
    • Keep Descriptions Visible: If possible, don’t hide the text—what helps screen reader users can help sighted users, too.
    • Use Native HTML First: ARIA is a supplement, not a substitute.
    • Test Often:
      • Use screen readers like NVDA, JAWS, and VoiceOver.
      • Test in browsers like Chrome, Firefox, and Safari.
    • Stay Consistent:
      • Create reusable components.
      • Document your design patterns.
      • Automate accessibility checks.

    This also applies to any content with captions and subtitles—they should be clearly described in a way that works for both visual and non-visual users.

    Beyond the Code: Organizational Tips

    • Code Reviews Should Include Accessibility
    • Use Linters and Audits: Tools like Google Lighthouse or  WAVE to catch ARIA  barriers.
    • Add Accessibility to Your QA Checklist
    • Train Your Team: Make sure everyone knows what ARIA does and doesn’t do.

    If you’re building tools with captions and subtitles, include accessibility from the start. Don’t bolt it on later.

    Accessible Descriptions, Better UX

    aria-describedby is one of those quiet heroes of accessibility. It helps fill the gaps between what users see and what assistive tech can tell them.

    Used well, it improves the user experience for everyone—not just people using screen readers. It’s especially helpful in forms, dialogs, and anything with captions and subtitles, where the added context can be critical.

    So remember: use aria-describedby intentionally, test it thoroughly, and keep your patterns consistent. And if your team needs help making your site or app more accessible, 216digital offers expert guidance to help you meet compliance standards—while creating a better experience for all users.

    Let’s keep building an internet that works for everyone. One line of code at a time.

    Greg McNeil

    April 11, 2025
    How-to Guides
    ARIA, aria-describedby, How-to, Web Accessibility, web developers, web development, Website Accessibility
216digital Scanning Tool

Audit Your Website for Free

Find Out if Your Website is WCAG & ADA Compliant













    216digital Logo

    Our team is full of expert professionals in Web Accessibility Remediation, eCommerce Design & Development, and Marketing – ready to help you reach your goals and thrive in a competitive marketplace. 

    216 Digital, Inc. BBB Business Review

    Get in Touch

    2208 E Enterprise Pkwy
    Twinsburg, OH 44087
    216.505.4400
    info@216digital.com

    Support

    Support Desk
    Acceptable Use Policy
    Accessibility Policy
    Privacy Policy

    Web Accessibility

    Settlement & Risk Mitigation
    WCAG 2.1/2.2 AA Compliance
    Monitoring Service by a11y.Radar

    Development & Marketing

    eCommerce Development
    PPC Marketing
    Professional SEO

    About

    About Us
    Contact

    Copyright 2024 216digital. All Rights Reserved.