ARIA Describedby Usage

ARIA describedby provides supplementary descriptions for elements, giving screen reader users additional context beyond the accessible name. This attribute connects elements to descriptive text that explains purpose, format requirements, or other helpful information.

What Is ARIA Describedby

The aria-describedby attribute references one or more elements whose text content provides a description for the current element. Unlike aria-labelledby which provides the name, aria-describedby provides extended information announced after the name and role.

When a screen reader encounters an element with aria-describedby, it announces the element’s name and role first, then the description. A form input might announce “Password, edit, must contain at least 8 characters with one number.” The description “must contain at least 8 characters with one number” comes from aria-describedby.

This separation between name and description serves different purposes. The name identifies what the element is. The description provides additional context, instructions, or error information that helps users interact with the element correctly.

How ARIA Describedby Works

aria-describedby references elements by ID, similar to aria-labelledby. The attribute value contains one or more space-separated IDs. Screen readers concatenate the text content of all referenced elements to form the description.

The referenced elements can be visible or hidden. Visible descriptions benefit all users. Hidden descriptions using CSS like visibility: hidden or display: none may still be read by some screen readers, though visibility behavior varies. The clip pattern or sr-only class provides reliable hiding while maintaining screen reader access.

Multiple descriptions can combine through multiple ID references. An input might reference both a hint element and an error element. The screen reader announces both pieces of information, typically in the order the IDs appear in the attribute value.

aria-describedby differs from aria-description (introduced more recently), which accepts a text string directly rather than referencing elements. aria-describedby remains better supported and more commonly used.

Design systems use aria-describedby to connect form inputs to helper text, error messages, and format hints. Component implementations handle the ID generation and attribute management automatically.

Key Considerations

• Use aria-describedby for supplementary information, not primary identification
• Reference visible text when the description benefits all users
• Ensure referenced IDs exist and contain meaningful text
• Order multiple ID references logically (hints before errors, for example)
• Keep descriptions concise as they are announced linearly
• Do not duplicate information already in the accessible name
• Update aria-describedby dynamically when descriptions change

Common Questions

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

aria-labelledby provides the accessible name: the primary identifier announced immediately with the element. aria-describedby provides additional description announced after the name and role.

Names should be brief and identify the element. Descriptions can be longer and provide context. “Email address” is a name. “Enter the email you used to register” is a description. Using aria-labelledby for long instructions or aria-describedby for primary identification reverses their intended purposes.

When should descriptions be visible versus hidden?

Visible descriptions benefit all users, not just screen reader users. Helper text explaining format requirements, hints about expected input, and instructions help everyone. Visible descriptions should be the default choice.

Hidden descriptions make sense for information redundant for sighted users who can see visual context. However, hiding information often indicates it might benefit everyone if visible. Evaluate whether hidden descriptions should become visible before defaulting to screen-reader-only content.

How should aria-describedby handle dynamic content?

Form validation commonly updates descriptions dynamically, adding error messages when validation fails. The aria-describedby attribute should reference error message containers from the start, even when empty.

When errors appear, the content changes but the reference remains stable. Some screen readers announce changes to describedby content when the element has focus. Pairing with aria-live on the error container ensures announcements when errors appear.

Summary

ARIA describedby connects elements to supplementary text that provides additional context beyond the accessible name. Through ID references to visible or hidden descriptive text, this attribute enables screen reader users to access instructions, hints, and error information that supports successful interaction.