Names, descriptions, and hiding
The name is the short label a screen reader speaks when it lands on a control. The description is extra help spoken after it. Hiding removes something from what assistive technology sees. Three different jobs, and mixing them up is the most common ARIA bug.
In one minute
- Name = what it is called ("Save invoice"). Description = how to use it ("Saves as a draft"). Never swap them.
- The browser picks a name by priority:
aria-labelledby, thenaria-label, then the element's own label or text, thentitleas a last resort. - The visible text must be inside the accessible name, so voice-control users can say what they see (WCAG 2.5.3).
aria-hidden="true"removes something from the tree but leaves it on screen. Never put a focusable control inside it.
A name is the label on a jar: "Flour". A description is the small print: "Store in a cool place". Hiding is putting the jar in a cupboard: still in the house, but nobody walking through the kitchen sees it. If you hide a jar someone needs to reach, they will bump into the cupboard.
1. How the browser chooses a name
The accessible name computation walks sources in priority order and stops at the first one that has text. Author-provided names beat the element's own text. Tick the sources below to add them to one button and watch which one wins.
Step 1. Tick the sources that exist on the button.
aria-labelledbypoints at one or more ids. Their text is joined in the order you list the ids. The target does not have to be focusable, and can even be hidden.aria-labelis the whole name. It replaces the visible text in the tree and does not add to it.- If nothing in the author sources exists, the host language names it:
<label for>,alt, the button's own text, the<summary>text,<caption>. titleis the last-resort fallback. When another source already gave the name,titlebecomes the description instead.
2. The name must match what people see
Voice-control users say the words they see: "click Save invoice". If your aria-label says something else, the
command fails. WCAG 2.5.3 Label in Name says the visible text must be contained in the accessible name, ideally at the start.
Step 2. The button shows "Save invoice". Choose its aria-label, then see what voice control and a screen reader do.
A good rule: if the control has visible text, do not use aria-label. If it has to be used, repeat the visible words first, then add more if needed ("Save invoice as draft").
3. Description is not name
aria-describedby points at help text: a hint, a format example, an error. Screen readers speak it after the name and
the role, or on request. A field still needs a real label. Try the four versions of a password field. Tab into the field to feel it.
Related attributes: aria-description gives a string description when there is nothing to point at. aria-details points at longer related
content (a footnote, a definition) that assistive technology can offer as a jump, not as the name and not as the short description.
Prefer aria-describedby so the hint is also visible to everybody.
4. Hiding: aria-hidden and its traps
aria-hidden="true" removes an element and everything inside it from the accessibility tree while leaving it on
screen. Use it for decoration (icons that repeat nearby text). The deadly mistake is hiding something you can still
Tab to. Pick a case, then press Tab into the demo.
| Technique | On screen | In the tree | Tab stop |
|---|---|---|---|
hidden / display:none | ✕ Hidden | ✕ Removed | ✕ No |
visibility:hidden | ✕ Hidden | ✕ Removed | ✕ No |
aria-hidden="true" | ✓ Visible | ✕ Removed | ✓ Still yes (bug) |
Visually hidden text (.sr-only) | ✕ Not seen | ✓ Present | depends on element |
aria-hidden="false" asks to expose a node that would otherwise be hidden, but it cannot override display:none and is unreliable. Avoid it.
If a modal is open and you want to hide the page behind it, use the inert attribute, which hides it from the tree and removes tab stops.
5. The attribute cheat sheet
Every naming, describing and hiding attribute in one place.
| aria-labelledby | Ids of elements whose text is the name. Use it when the label is already visible somewhere else on the page. Multiple ids are joined in order. The referenced nodes do not have to be focusable. |
|---|---|
| aria-label | A string that replaces the accessible name. Use it for an icon button whose graphic has no text. Do not use it to "clarify" a button that already has a visible label. |
| aria-describedby | Ids of extra description: a hint, a format example, an error paragraph. This is not the name. A field still needs a label. Description is announced after the name, or on a describe command, depending on the screen reader. |
| aria-description | A string description when there is no element to point at. Same job as aria-describedby, lower priority than an id reference. Prefer describedby so the hint is visible. |
| aria-details | Ids of longer related content, such as a definition or a footnote. Assistive tech can offer it as a jump, not as the name and not as the short description. |
| aria-roledescription | Replaces the localized role name users hear ("button" becomes "attachment"). Use it rarely. If you override the role name, people lose the standard word they use to operate that control. Never use it to fake a role the platform does not support. |
| aria-braillelabel | A braille-specific name when the speech name would braille badly, for example an abbreviation you want spelled one way in speech and another in braille. If you set it, you should also set aria-label or aria-labelledby. It does not replace the speech name. |
| aria-brailleroledescription | The braille form of aria-roledescription. Same caution: only when the spoken role description brailles poorly. It does not change the spoken role. |
| aria-keyshortcuts | Documents a shortcut that you implemented, such as "Alt+S". It does not bind the keys. The string should look like the shortcut the user actually presses. |
| aria-hidden | true removes the element and its descendants from the accessibility tree while leaving them on screen. false asks to expose a node that would otherwise be hidden. Never put a focusable control inside aria-hidden="true". Keyboard users can land on something the screen reader cannot see. |
6. Which roles can, must, or cannot have a name?
Some roles require a name (an unnamed button is announced as "button", which is not a name). Some roles
prohibit one: aria-label and aria-labelledby on them are invalid and are ignored. Pick a role.
Prohibited: caption, code, definition, deletion, emphasis, generic,
insertion, mark, none (same as presentation), paragraph, strong,
subscript, suggestion, superscript, term, time, tooltip. Name the control inside them,
or the figure or table they caption. Required (if you use them): button, checkbox, combobox,
heading, link, slider, switch, tab, and the other "name required" widgets in lesson 18.
Common mistakes
| You see | Why it is a problem | Fix |
|---|---|---|
| Icon button with no name | Announced as just "button". | aria-label or hidden text. |
aria-label="Submit" on a button showing "Save" | Voice control "click Save" fails. | Match the visible text. |
| Hint text used as the label | Name becomes a long instruction. | Real label plus aria-describedby. |
| Placeholder as the only label | Disappears when typing. | Visible <label>. |
aria-hidden="true" on a container with a button | Focus lands on something invisible to the screen reader. | Use inert or hidden. |
aria-label on a div or span | Role generic prohibits a name. | Add a real role, or put the text in the content. |
- In lab 1, tick every box and read the order list. Then untick one at a time from the top. How does the name change?
- In lab 4, choose "Hide a focusable button" and press Tab. Read the message.
- Inspect an icon button on a real site. If its name is empty, write the
aria-labelit should have.
Remember
- Name priority:
aria-labelledby,aria-label, native label or content,title. - Visible text must appear in the name (WCAG 2.5.3). Prefer no
aria-labelwhen text exists. - Description (
aria-describedby) adds help. It never replaces a label. aria-hiddenis for decoration only. Never on or around focusable controls.- Some roles require a name, some forbid one.