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-labelledbygives something its name.aria-describedbygives 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:
- 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.