Glossary · Accessibility term
Accessible name
The accessible name is what assistive technology announces an element as, the words a screen reader speaks when it lands on a button or a link. It is computed rather than declared, from the text inside the element, a label, alt text, or ARIA attributes, and the order they are consulted in is what surprises people. It runs aria-labelledby first, then aria-label, then whatever the element's own technology supplies such as a label or alt text, then the text inside, and title last of all. So an aria-label on a button beats the words printed inside it, while a title loses to almost everything and is a fallback rather than an override. Some elements cannot be named at all, because their role forbids it, which is why the attribute sometimes does nothing whatever. And an element with no name is announced as its role and nothing else. "Button." "Link." "Edit text." The reader knows something is there and has no idea what it does.
In practice
For a button with words inside it, the name is those words and you have nothing to do. For an icon-only button there is no text to use, so the name has to come from somewhere else. An aria-label supplies one directly. An aria-labelledby points at text on the page. Visually hidden text inside the button works too, and it works for a reason worth knowing. For name computation, text clipped to nothing or moved off screen still counts as available, while display:none inside the element does not, which is exactly why the standard visually-hidden pattern clips rather than hiding. There is one deliberate way round that. Point aria-labelledby at an element and its text is used even where that element is hidden, which is how a shared label can sit in the markup once and never be seen.
The precedence is where the bug lives. An aria-label beats the element's own contents, so a button reading Buy now on screen and carrying aria-label="Submit" is announced as Submit. Somebody using voice control who says click Buy now may get nothing, because the name they can see is not the name the software matched against. The fix is not a better label. It is to leave the name alone and put the extra context in aria-describedby, which feeds the description rather than the name and is usually read out after it, though when and whether it is read is the reader's software to decide.
The name is a flat string with all the structure thrown away, so a button built from several elements with line breaks and emphasis produces one run-on announcement. And the words around it are not yours to control either, because the screen reader adds the role description itself and decides the order. The same button is OK button in one and push-button OK in another, which is one reason the same page sounds different in JAWS, NVDA and VoiceOver.
Why it matters
This one property decides whether a control is usable by somebody who cannot see it, and two rules ride on it. Name, Role, Value requires every control to expose a name at all. Label in Name requires that where a control shows visible text, its name contains that text, and it sits at Level A, which makes it a floor rather than a refinement. That second rule exists mainly for people using voice control, who navigate by saying aloud what they can read on screen. When the two names disagree, the control is visible, obvious, and unreachable.
The rule to remember
Where a control shows text, its name has to contain that text, and putting the visible label at the start of the name is the recommended shape. Capitalization and most punctuation get ignored, because somebody speaking a label says neither. What is not ignored is a word swap. A button showing 11x3 whose name reads eleven multiplied by three will not match a person saying eleven times three.
Where this shows up on the site
Related terms
- ARIAARIA is a set of attributes that tell assistive technology what a custom control is and what state it is in.
- Name, Role, ValueName, role and value are the facts assistive technology needs about a control, and the shorthand quietly drops one.
- Accessibility treeThe accessibility tree is a second structure the browser builds alongside the DOM, holding one object for every part of your page that has to be exposed to assistive technology.
- Form labelA form label is the visible text naming a field, tied to that field in code so software can tell which words belong to which box.
- RoleA role is what kind of thing an element is, as reported to assistive technology.
- TooltipA tooltip is a small label that appears when something takes hover or focus.
- Text alternativeA text alternative is the standard's own term for text attached to something that is not text, in a way software can follow from one to the other.
- Accessible descriptionAn accessible description is the extra line a screen reader reads out after the name, and the word the specification uses for what it does is complements.
Knowing the word is the easy part.
Find out where your own site stands. The free scan checks 10 pages in a real browser against all 90 supported automated rules, separates 27 best-practice checks from its WCAG findings, and names the rule behind every result.