aria‑describedby Visualizer

aria-describedby is an ARIA attribute that establishes a relationship between an element and the text that describes it. When a screen reader user focuses on the element, the assistive technology reads the element's label and then the content of the referenced description element(s). It takes one or more ID references (space-separated). Common uses include associating form fields with error messages, hint text, or supplemental instructions. Unlike aria-labelledby which provides the accessible name, aria-describedby provides additional descriptive information.

aria-labelledby defines the accessible name of an element — it replaces the element's native label. aria-describedby provides supplementary information that is announced after the name and role. Think of it this way: aria-labelledby = "what is this?" and aria-describedby = "tell me more about this." An element can have both attributes simultaneously, and both accept multiple space-separated ID references. Screen readers typically announce the description after a short pause, allowing users to hear the label first.

Yes! aria-describedby accepts multiple space-separated ID references, like aria-describedby="hint1 error1 note1". Screen readers will concatenate the text content of all referenced elements and announce them in the order they appear in the attribute value. Each ID is checked independently — if any referenced ID doesn't exist in the DOM, that specific reference is broken. Use our tool above to validate all your ID references at once.

Common reasons include: (1) The referenced ID doesn't exist in the DOM (typo or missing element) — our visualizer will flag these as "Broken." (2) The description element is empty or contains only whitespace. (3) The description element is dynamically removed or not yet rendered when the page loads. (4) The element with aria-describedby is not focusable or not exposed to the accessibility tree (e.g., it has aria-hidden="true" or display:none on itself). (5) Some screen readers may not support aria-describedby on certain roles — check the ARIA specification for supported roles.

Description elements referenced by aria-describedby can be visually hidden (e.g., using the CSS .sr-only clip technique) and screen readers will still announce their content. However, avoid using display:none on description elements, as this removes them from the accessibility tree entirely and screen readers won't find them. The safest approach for visually hidden descriptions is the classic screen-reader-only CSS pattern: position:absolute; width:1px; height:1px; overflow:hidden; clip:rect(0,0,0,0);. That way the text remains accessible to assistive technology while being invisible to sighted users.

Use this visualizer tool to check your HTML for valid ID references. Then test with actual screen readers: NVDA (free on Windows), VoiceOver (built into macOS/iOS), or JAWS (Windows). You can also use browser DevTools: inspect the element and check the Accessibility panel to see its computed description. Chrome's Accessibility tab shows the "Description" field populated by aria-describedby. For automated testing, tools like axe-core, Lighthouse, and WAVE can detect missing or broken ARIA references.

Keep descriptions concise — screen reader users hear this text every time they focus the element. Don't duplicate the label in the description; use it for supplementary info only. Ensure referenced IDs are unique and exist in the DOM before the attribute is parsed. Use it for dynamic content like live error messages — when the description element's text changes, many screen readers automatically announce the update. Avoid chaining — don't have a description element that itself references another description via aria-describedby, as this creates confusing announcement orders. Test with real assistive technology to confirm the reading order feels natural.