Accessible Descriptions

Accessible descriptions provide supplementary information beyond an element's accessible name. In ARIA, `aria-describedby` commonly connects an element to descriptive text elsewhere in the same document.

An accessible name identifies what an element is or does, while an accessible description supplies additional context. For example, a button might have the name "Delete" and a description explaining that the action permanently removes an item. This distinction helps assistive technology users understand consequences or supporting details.

The usual pattern is `aria-describedby="some-id"`, where the value references the `id` of an element containing the description. Multiple IDs can be supplied as a space-separated list. The referenced content can be visually visible or hidden, as long as it provides appropriate descriptive text.

Use `aria-describedby` when the description already exists as DOM content. For example, a form field can point to helper text explaining formatting requirements. If the additional information is complex, lengthy, or has meaningful structure that users need to navigate, `aria-details` may be more appropriate.

`aria-describedby` differs from `aria-labelledby`: the label gives the concise identity or purpose of the element, while the description adds supporting information. Native HTML labeling mechanisms should generally be preferred when they already express the relationship correctly. For example, use a `` for a form control's primary label and reserve `aria-describedby` for supplementary help or instructions.

Key points

• `aria-describedby` associates an element with supplementary descriptive text.
• Its value contains one or more space-separated DOM `id` references.
• An accessible description adds context; it is not the element's primary accessible name.
• Use `aria-labelledby` for labeling and `aria-describedby` for additional descriptive information.
• Prefer `aria-details` when associated content is long, structured, or requires navigation.

Interview questions

What is `aria-describedby` used for?

It associates an element with additional descriptive text. The attribute contains the ID of an element that provides that text. Assistive technologies can use this relationship to expose extra context beyond the element's accessible name. A common example is helper text for a form field.

How would you add accessible help text to an input?

Give the help text its own unique `id`, then reference that ID with `aria-describedby` on the input. Keep the primary field label separate, normally using a native ``. This lets the label identify the field while the description supplies additional instructions.

What is the difference between `aria-labelledby` and `aria-describedby`?

`aria-labelledby` establishes an accessible name using referenced content, while `aria-describedby` provides an accessible description. The name should concisely identify the element, whereas the description can provide supporting information or instructions. For a text field, a visible `` commonly provides the name and `aria-describedby` can point to validation or usage guidance.

When would you use `aria-details` instead of `aria-describedby`?

`aria-describedby` is designed for descriptive text that can be treated as a flat textual description. If the associated information is lengthy, structured, or contains semantics that users need to navigate, `aria-details` is more appropriate. The distinction matters because flattening structured information into a description can lose useful relationships and navigation. The choice should therefore reflect the structure and interaction needs of the content.