Category: ARIA and Semantic Structure

aria-describedby

Also known as: aria-describedby property, aria-describedby attribute

Simply put

aria-describedby is a WAI-ARIA attribute that connects an element, such as a form field, image, or widget, to other text on the page that describes it. When a person uses a screen reader, that linked description can be announced to give additional context beyond the element's main label. It works by pointing to the id values of the elements that contain the descriptive text.

Formal definition

aria-describedby is a WAI-ARIA property that establishes a programmatic relationship between an element and one or more other elements that describe it, using a space-separated id reference list. Assistive technologies generally use the referenced content to provide supplementary descriptive information distinct from the element's accessible name. It is documented in W3C WCAG techniques (for example, ARIA1 for form fields and ARIA15 for image descriptions) as a technique that may help satisfy relevant success criteria; note that WCAG techniques are advisory and that support behavior can vary across assistive technologies, so manual testing is recommended.

Why it matters

Many interface elements need more explanation than a short label can provide. A password field may require formatting rules, a form control may have associated error or hint text, and an image or diagram may need a longer description. aria-describedby lets developers connect these elements to that descriptive text programmatically, so a screen reader can announce the supplementary information after the element's accessible name. Without such a relationship, the description may appear visually but never reach assistive technology users, leaving them without context that sighted users receive.

The attribute is referenced in W3C WCAG techniques, such as ARIA1 for associating descriptions with form controls and ARIA15 for providing descriptions of images. These techniques are advisory ways that may help satisfy relevant success criteria rather than requirements in themselves. Using aria-describedby appropriately can support a more usable experience, but meeting a technique does not by itself guarantee conformance, an accessible experience for all users, or immunity from legal claims.

Support behavior for aria-describedby can vary across browsers and assistive technologies, and how and when the referenced text is announced is not uniform. For this reason, teams should not assume that adding the attribute resolves an accessibility barrier. Manual testing with actual screen readers, alongside automated checks, is recommended to confirm that the description is conveyed as intended. This entry is general guidance and not legal advice; requirements and testing expectations evolve, and organizations should consult qualified professionals for their specific circumstances.

Who it's relevant to

Front-end developers and engineers

Developers implement aria-describedby when connecting form fields to hint or error text, associating images or diagrams with longer descriptions, or adding context to custom widgets. They are responsible for ensuring the referenced id values point to real elements containing the intended text and for testing the result with assistive technologies rather than relying on the attribute's presence alone.

Accessibility specialists and QA testers

Those evaluating accessibility use aria-describedby as one signal of a programmatic relationship between an element and its description. Because support and announcement behavior vary across screen readers and browsers, and because automated tools detect only a portion of issues, specialists should confirm through manual and assistive technology testing that the description is actually conveyed.

UX designers and content authors

Designers and content authors define what supplementary information a control, image, or widget needs and how it should be worded. Clear, concise descriptive text improves the value of the relationship established by aria-describedby, and coordinating with developers helps ensure that on-screen hints and descriptions are also exposed to assistive technology users.

Compliance and accessibility program leads

Program leads reviewing conformance efforts should understand that aria-describedby is referenced in advisory WCAG techniques rather than being a mandate in itself, and that using it does not guarantee conformance or legal compliance. They can use this understanding to set testing expectations and to identify where manual verification and, where appropriate, qualified legal counsel are needed.

Inside aria-describedby

aria-describedby attribute

A WAI-ARIA attribute that references the ID (or space-separated list of IDs) of one or more other elements whose text content provides a description for the element it is applied to.

ID reference mechanism

The attribute's value is one or more IDREFs pointing to existing elements in the DOM; the referenced elements supply the descriptive text that assistive technologies convey to users.

Accessible description

The information exposed through aria-describedby contributes to an element's accessible description, which is generally announced by screen readers after the accessible name and typically treated as supplementary rather than primary labeling.

Relationship to aria-labelledby

aria-describedby provides a description, while aria-labelledby (and other labeling methods) provide the accessible name; the two serve distinct purposes and are commonly used together on the same element.

Common use cases

Frequently used to associate help text, format hints, error messages, or additional instructions with form fields, buttons, and other interactive controls.

Common questions

Answers to the questions practitioners most commonly ask about aria-describedby.

Does aria-describedby make an element accessible on its own?

No. aria-describedby is one tool that associates descriptive text with an element, but adding it does not by itself guarantee an accessible experience. Its effectiveness depends on the referenced content being meaningful, the referenced IDs existing and being valid, and the overall interface being usable with assistive technology. Conformance with a single ARIA attribute does not equate to WCAG conformance, usability for all users, or legal compliance. Manual testing and testing with assistive technology are generally needed to confirm the description is announced as intended.

Is aria-describedby the same as aria-labelledby, or interchangeable with it?

No. The two attributes serve different purposes. aria-labelledby contributes to an element's accessible name, which is the primary identifier announced for the element. aria-describedby provides supplementary descriptive information that is generally announced after the name, often as additional context such as instructions, hints, or error details. Using one in place of the other can change how assistive technology conveys the element, so they should be selected according to whether the referenced text is the element's name or a description.

How do I associate a single element with multiple descriptions?

aria-describedby accepts a space-separated list of element IDs. You can reference more than one ID, and assistive technology will generally concatenate the referenced content in the order listed. Confirm that each referenced ID exists and is unique within the document, and verify the resulting announcement order through testing, as announcement behavior can vary across assistive technology and browsers.

Can I use aria-describedby to associate a form field with its error message?

Yes, aria-describedby is commonly used to associate a form field with hint text or an error message so that the description is announced when the field receives focus. Ensure the element containing the error message has a matching ID and contains readable text at the time the association is expected to be announced. Because timing and dynamic updates can affect whether the message is conveyed, this pattern should be verified with assistive technology, and it is often paired with other techniques for communicating validation state.

What happens if aria-describedby references an ID that does not exist?

If the referenced ID does not match an existing element, the description generally will not be announced, and no error is surfaced to the user. This is a common implementation defect that automated tools may or may not detect. Because automated testing catches only a portion of issues, references should be confirmed to point to present, populated elements, ideally through manual review and testing with assistive technology.

Is the content referenced by aria-describedby visible on screen?

It can be either. The referenced content may be visible to all users or may be visually hidden while remaining available to assistive technology, depending on how it is styled. If content is intended to be hidden visually but still announced, it should be hidden using techniques that keep it in the accessibility tree rather than methods such as display:none, which typically remove it from assistive technology as well. Verify the intended behavior through testing.

Common misconceptions

aria-describedby provides the element's name or label.

It supplies a description, not the accessible name. Naming is generally handled by a visible label, aria-label, or aria-labelledby, while aria-describedby adds supplementary information that assistive technologies typically announce separately.

The text can be placed directly in the aria-describedby value.

The attribute takes ID references, not literal text. It must point to the IDs of existing elements containing the descriptive text; putting the description string itself in the value will not work as intended.

Using aria-describedby guarantees an accessible experience.

Correct use of a single attribute does not ensure overall accessibility or legal compliance. Assistive technology support for descriptions can vary, and accessibility should be verified through manual and assistive technology testing rather than assumed from markup alone.

Best practices

Ensure every ID referenced by aria-describedby corresponds to an existing element in the DOM, since a broken or missing reference may result in no description being conveyed.

Use aria-describedby for supplementary information such as help text, hints, or error messages, and rely on labeling methods like a visible label or aria-labelledby for the accessible name.

When referencing multiple elements, provide a space-separated list of IDs and verify the order in which the descriptions are announced makes sense to users.

Test the resulting announcements with multiple screen readers and browsers, as support for descriptions can vary across assistive technologies.

Keep referenced descriptive text concise and meaningful, and update or remove references dynamically (for example, error messages) as the interface state changes.

Do not rely on aria-describedby alone to satisfy accessibility requirements; combine it with manual and assistive technology testing to confirm the intended experience.