aria-describedby

What is aria-describedby?

The aria-describedby attribute is part of WAI-ARIA, the Web Accessibility Initiative's Accessible Rich Internet Applications spec. An element with the attribute gets an accessible description by referencing the ID of one or more other elements already in the same DOM document.

Screen readers announce that description text right after the element's name, adding whatever extra context the element needs, from a short formatting hint to a full error message.

At a glance

Why is aria-describedby important when it comes to accessibility?

Sighted users often get extra context from a page's layout, for example from a hint sitting under a password field or a warning next to a delete button. Screen reader users don't get that same visual context unless the relationship is exposed in code.

The aria-describedby attribute makes that connection explicit, and it's how you build more accessible web applications around form controls, buttons, dialogs, and other elements with an explanation living elsewhere on the page.

This attribute is valuable when it comes to form fields, where a missing description can leave a screen reader user guessing at formatting rules or the reason a field failed validation.

A tooltip revealed on hover or a small icon carrying extra help text are common candidates too – sighted users get that context visually, while aria-describedby carries the same important information to screen reader users, helping them understand what a control does before they use it.

Ensuring you have accessible names and descriptions for form fields is a checkbox in most ADA compliance checklists.

Gaps like this often show up in accessibility audits, where a form or button has plenty of explanatory text on the page, but none of it is wired up for assistive technology to access.

How does aria-describedby work?

The WAI-ARIA specification calls aria-describedby a property; in HTML it's written as an attribute with a space-separated list of ID values, so one element can reference a single description or several at once.

When more than one ID is listed, browsers concatenate each referenced element's text content in the order the IDs appear in the attribute value, not the order those elements sit in the page's structure. Reorder the ID list, and the announced description adjusts to match.

The referenced element doesn't need to be visible. A description hidden with the HTML hidden attribute, or a CSS rule like display: none, still gets announced, as browsers calculate the description directly from the referenced element's text content rather than from what's rendered on screen.

Bear in mind that this only works within the same DOM document – aria-describedby can't reference a description hosted on a different page or an external resource.

The aria-describedby attribute takes precedence over the title attribute when browsers calculate an accessible description. If both are present on the same element, the title attribute's text is ignored.

The attribute is intended to be used for plain text descriptions. For instance, if the referenced content has a real structure that a screen reader user wants to navigate, like a list or a multi-paragraph explanation, aria-details is the better fit, because it lets assistive technology visit that content directly instead of having it read aloud as one flat string.

An aria-describedby example

Here is an example describing a password field's formatting requirements:

<label for="pw">Password</label>
<input type="password" id="pw" aria-describedby="pw-hint">
<p id="pw-hint">Must be at least 12 characters, including one number and one symbol.</p>

When focus lands on this input field, a screen reader announces "Password, edit, must be at least 12 characters, including one number and one symbol," reading the label and description together.

Referencing multiple descriptions works the same way, concatenated in the order listed:

<label for="username">Username</label>
<input type="text" id="username" aria-describedby="username-req username-tip">
<p id="username-req">Must be at least 8 characters long.</p>
<p id="username-tip">This will be visible to other users.</p>

aria-describedby also explains a button's function before someone commits to clicking it:

<button aria-describedby="delete-warning">Delete account</button>
<p id="delete-warning">This can't be undone. Any information entered into your profile will be permanently removed.</p>

A screen reader user hears the button's name, "Delete account," followed immediately by the warning – the same context a sighted user gets from reading the surrounding page.

aria-describedby vs. aria-label

These two attributes solve different problems rather than competing for the same one. Here are the use cases for each of these attributes.

aria-label writes a name directly into the attribute when no visible text can serve as one, and it should stay concise. aria-describedby points to text elsewhere on the page to supply detail a short name can't carry. A form field commonly uses both: a label for its name, and aria-describedby to associate it with a hint or error message referenced alongside it.

Common mistakes or misconceptions

• Referencing an ID that doesn't exist. A typo in the ID or a reference to an element that was later removed means the description is missing – browsers don't throw an error for a broken reference, so run an automated accessibility checker or test with a screen reader to catch it.
• Repeating what the label already says. If the accessible name already states the field's purpose, a description that restates it just forces screen reader users to listen to the same information twice.
• Piling on too many descriptions or using it for structured content. Every ID listed gets read aloud in full, so stacking unrelated descriptions buries the useful information in noise. A referenced list or multi-paragraph explanation fares no better; as covered above, aria-details is the right attribute for structured content.
• Assuming it behaves like a hyperlink. Despite the name, aria-describedby doesn't create a visible or clickable link between two elements; it's a programmatic reference read by assistive technology, not something a user can click through.
• Expecting dynamic updates to announce consistently. Different screen readers handle changes to a referenced description differently, so if that text updates while someone is interacting with the element, say inside a role="alert" region, test it rather than assuming it will be fine.