Accessible Names
What assistive technology announces for a control, which must match what a user would call it.
Definition
The accessible name is computed from several sources in a defined order: aria-labelledby, then aria-label, then native labelling such as a label element or the element's own text content. Every interactive element needs one.
Craft convention. True because the industry converged on it. Breaking it costs familiarity, not correctness.
On this plate
Reach for this when
- Any icon-only control.
- Building custom components.
- Reviewing ARIA usage.
Common mistakes
- aria-label contradicting the visible text.
- Icon buttons with no name at all.
- Duplicate landmark regions with no distinguishing names.
Rules
- Prefer visible text as the name. A visible label serves everyone, including speech input users who say the label aloud.
- WCAG 2.5.3 requires the accessible name to contain the visible label text, and to begin with it where possible.
- Use aria-label only where no visible label exists, such as an icon-only button.
- Do not use aria-label to override a visible label with different wording. Speech control users will say the visible words.
- Give each landmark region an accessible name when there is more than one of a type, such as two nav elements.
- Do not put a title attribute in place of a label. It is inconsistently exposed.
How the name is worked out
Highest wins. Knowing the order explains most cases where a control announces something nobody wrote.
| Source | Precedence | Notes |
|---|---|---|
| aria-labelledby | Highest | Wins over everything, including a visible label element. Useful for composing a name from existing text. |
| aria-label | Next | Invisible. Use only where no visible label exists, and keep it matching what a reader would say. |
| The native label | Next | A label element, a fieldset legend, a button's own text, or an image's alt text. |
| Other host-language attributes | Next | Placeholder text can end up here as a fallback, which is why a placeholder-only field seems to work and then does not. |
| title | Lowest | Inconsistently exposed, invisible on touch, and unreliable as a name. |
Naming controls
Do
- Start the accessible name with the visible label text, which is what WCAG 2.5.3 requires and what voice control depends on.
- Name icon-only buttons after the action: Delete invoice, not Bin icon.
- Name each landmark when there is more than one of a type, such as primary and footer navigation.
- Include the object in the name where a row repeats the same action many times: Delete invoice 4021.
Do not
- Do not override a visible label with different wording in aria-label.
- Do not name a control after its appearance or its position on the screen.
- Do not leave an icon button unnamed. It announces as button, and there is nothing the reader can do with that.
- Do not put the whole sentence in the name and nothing in the description. Long names are read every time focus lands.
Commonly confused with
Close neighbours that get substituted for each other. The difference is stated first, then the condition that picks one over the other.
Alt Text
AccessibilityThe text alternative carried by an image, describing what the image contributes.
Key difference
Alt text is one way an accessible name gets computed, and it only applies to images. Buttons, inputs, links and regions all need names too, computed from labels, content or ARIA.
Use Accessible Names when
- The element is a button, input, link, dialog or landmark.
- An icon-only control announces nothing useful.
- You are debugging what a screen reader actually says.
Use Alt Text when
- The element is an image, icon graphic or chart.
- You are deciding between describing it and hiding it.
- The question is what the picture is for, not what it is of.
Labels and Instructions
AccessibilityThe visible label and any format instruction, present before the reader types.
Key difference
A label is what everyone sees beside the field. The accessible name is what assistive technology announces. They should match; when they do not, the visible label is usually right and the name has been overwritten by an aria attribute.
Use Accessible Names when
- The control is an icon button, a link or a region rather than a field.
- A screen reader announces something different from the visible text.
- You are debugging aria-label, aria-labelledby or a label association.
Use Labels and Instructions when
- The field has no visible label, or only a placeholder.
- A format requirement is discovered by getting it wrong.
- The audience is everyone, not only assistive technology users.
Local chart
A11Y·008 · Region V · Grid A3
This entry and the entries it is stated to connect with. Each line is labelled with what the connection means.
Sources
Where a source establishes something narrower than the popular reading of it, the note says so.
- [1]
Understanding Success Criterion 2.5.3: Label in Name
W3C, WCAG 2.1
Continue from here
Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.
Applies when you are designing
Relied on by
Entries that assume this is already in place.
- AvatarCMP·024 · Component
- ButtonCMP·001 · Component
- LinkCMP·002 · Component
- AuthenticationPAT·023 · Pattern
- Button and Action LabelsWRT·008 · UX writing
The label is usually the accessible name, so vague copy is an accessibility defect as well as a writing one.
Short definition
The one-paragraph version, for when that is all you need.
- ARIATERM·074 · Term
- Assistive TechnologyTERM·075 · Term
Related concept
Connected closely enough to change how you apply this.
- Keyboard NavigationA11Y·002 · Accessibility
- Screen ReadersA11Y·005 · Accessibility
- IconographyFND·050 · UI foundation