Accessible Name
An accessible name is the programmatically determined label that assistive technologies use to identify an interface element.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/accessible-name/
01What it means
An accessible name identifies the purpose of a control, landmark, image, or other element in the accessibility tree. Browsers compute it from sources such as associated labels, element content, alternative text, or ARIA naming attributes according to a defined precedence. It is distinct from an accessible description, which supplies supplementary detail.[1][2]
- 01Element purposeMeaning outside visual context
- 02Native visible labelPreferred persistent source
- 03Alternative namingElement content, alt, ARIA when needed
- 04Name computationBrowser applies defined precedence
- 05Accessibility treeInspect ambiguous and changing controls
The accessible name identifies the element; an accessible description supplies supplementary detail. Keep the name aligned with visible wording.
02Why it matters
Screen-reader users navigate and operate interfaces through announced names, roles, states, and values. Clear names also support voice control, automated testing, and consistent component APIs; missing or mismatched names make controls difficult or impossible to identify.
03When to use it
Ensure every interactive element and any non-text content requiring identification has an appropriate accessible name. Prefer visible text and native labeling mechanisms; use ARIA naming when native semantics cannot express the relationship.
04How it works
- Identify what each element needs to communicate when encountered outside its visual context.
- Provide a persistent visible label and associate it with the element using native HTML where possible.
- Use alternative text or ARIA naming only for cases that native content and labels do not cover.
- Keep the accessible name aligned with visible wording, especially for speech-input users.
- Inspect the computed accessibility tree and test ambiguous, repeated, icon-only, and changing controls.
05A practical example
A magnifying-glass icon button has visible nearby text “Search” and the same computed accessible name. When it changes to a close action, both the icon and accessible name change to “Close search,” so visual, screen-reader, and voice-control users receive one consistent purpose.
06Where it breaks
A correct name does not supply keyboard behavior, focus handling, role, state, or clear visible design. Naming rules have precedence, so adding aria-label can unexpectedly replace useful descendant text; assistive-technology output can also vary.
Common mistakes
- Using placeholder text as the only name for a form field.
- Giving a control an accessible name that differs from its visible label.
- Adding aria-label when existing native text already provides the correct name.
- Confusing an accessible description or tooltip with the primary name.
07Sources
- Accessible Name and Description Computation 1.2World Wide Web Consortium · Technical specificationAccessible Name and Description Computation 1.2
- Understanding Success Criterion 4.1.2: Name, Role, ValueW3C Web Accessibility Initiative · Standards guidanceUnderstanding Success Criterion 4.1.2: Name, Role, Value