Accessible names and aria-label: how they are computed
An accessible name is what assistive technology announces for an element, computed from its content, label, aria-label or aria-labelledby. How it works.
An accessible name is the text assistive technology announces for an element, such as “Search” for a button or “Email address” for a field, worked out from the element’s content, its label or ARIA attributes.
W3C’s Accessible Name and Description Computation specification sets the order. aria-labelledby wins, then aria-label, then the native label: a <label> for a form field, alt for an image, a <caption> for a table. Then comes the element’s own text for roles that take their name from content, such as buttons and links, and finally title. The Authoring Practices Guide’s advice is to prefer visible text, and to treat aria-label as the fallback when there is nothing visible to point at. WCAG success criterion 4.1.2, Name, Role, Value, requires every user interface component to have a name that can be determined by software.
Category: Accessibility
Why it matters
A control with no name is announced as “button” or “edit text” and nothing else. Icon buttons are the usual case: a magnifying glass, a cross or a hamburger menu that is obvious to a sighted user is silent to a screen reader. Voice control users hit a different problem. They say the words they can see, so a button that shows “Search” but is named “Find products” does not respond to “click Search”. WCAG 2.5.3, Label in Name, asks that the name contain the visible text for that reason.
How squirrelscan checks it
Fourteen hand-written rules check names, each for a kind of element. a11y/button-name and a11y/aria-labels cover buttons and clickable SVGs. a11y/aria-input-field-name, a11y/select-name and a11y/aria-toggle-field-name cover fields, selects, checkboxes and radios. a11y/aria-command-name covers links and menu items, and a11y/aria-dialog-name covers dialogs. a11y/frame-title covers iframes. Meters, progress bars, tooltips and tree items each have their own rule, and a11y/table-duplicate-name flags tables that share or lack a name on pages with more than one. a11y/label-content-name-mismatch fails an aria-label that does not contain the element’s visible text.
Most of these rules skip elements hidden from the accessibility tree, and report ones a style may hide in a way squirrelscan cannot settle as unconfirmed. An icon drawn by a CSS pseudo-element is not in the markup, so such a button reads as empty.
| Rule | What it flags | Severity |
|---|---|---|
| aria-label: which elements need one and how to check | Buttons, links and inputs with no visible text and no aria-label have no name for screen readers. squirrel finds every one on every page. | error |
| Accessible names for buttons: what counts and how to check | A button with only an icon has no name for a screen reader. squirrel lists every button on every page that has nothing to announce. | error |
| Input fields with no accessible name, ARIA and native | Text boxes, comboboxes and sliders that announce nothing. squirrel checks the nine ARIA input roles alongside native inputs and selects. | error |
| Command roles: buttons, links and menu items need names | Anything that performs an action has to announce what it does. squirrel lists every command element on a page with no accessible name. | error |
| Dialog accessible name: role=dialog and the dialog element | A modal with no name leaves screen reader users guessing what just opened. squirrel checks ARIA dialogs and native dialogs separately. | error |
| Dropdowns with no accessible name: naming a select | A select announced only as ‘combo box’ gives no clue what it changes. squirrel checks every select element on the page. | error |
| iframe title: naming embedded frames for screen readers | An iframe with no title is announced as just ‘frame’. squirrel checks every iframe and frame element on the page. | error |
| Visible label missing from the accessible name | A button showing ‘Search’ with aria-label ‘Find products’ may not respond when a user speaks its visible label. squirrel compares the two. | error |
| Accessible name for a meter element and role=meter | A gauge that announces only a number tells a screen reader user nothing. squirrel checks native meter elements and role=meter. | error |
| Accessible name for a progress bar and role=progressbar | A progress bar with no name announces a percentage and nothing else. squirrel checks native progress elements and role=progressbar. | error |
| Checkboxes, radios and switches with no accessible name | A checkbox that announces only its role gives no reason to tick it. squirrel checks toggle roles and native checkbox and radio inputs. | error |
| role=tooltip with no content: what to check | A tooltip with nothing to announce leaves the control it explains unexplained. squirrel checks every role=tooltip element on the page. | error |
| role=treeitem: naming every node in a tree | A tree node that announces only its position in the tree is unusable. squirrel checks every role=treeitem for something to read out. | error |
| Tables sharing a name, and tables with none | Several tables on one page need distinct names or a screen reader’s table list is unusable. squirrel checks captions and labels. | warning |
How to fix it
Name the element that has the role, not the icon inside it, and hide the icon:
<button aria-label="Close settings">
<svg aria-hidden="true">...</svg>
</button>
<button aria-label="Search products">Search</button>Prefer a visible <label> for form fields, which also makes the words clickable (the select fix, the field fix). Point a dialog’s aria-labelledby at its visible heading (the dialog fix). Start an aria-label with the visible words (the mismatch fix), and describe an iframe’s content rather than the vendor (the frame fix).
Run the check
squirrel audit https://example.com --rule-include a11y/aria-labels,a11y/button-name,a11y/aria-input-field-name,a11y/aria-command-name,a11y/aria-dialog-name,a11y/select-name,a11y/frame-title,a11y/label-content-name-mismatch,a11y/aria-meter-name,a11y/aria-progressbar-name,a11y/aria-toggle-field-name,a11y/aria-tooltip-name,a11y/aria-treeitem-name,a11y/table-duplicate-nameA signed-out local audit costs nothing.
Related terms
- ARIA: Accessible Rich Internet Applications: roles, states and properties that describe custom widgets to assistive technology.
- Form labels: The
<label>or accessible name tied to each form control, plus autocomplete tokens, so people know what to enter. - Anchor text: The visible, clickable text of a link, which tells readers and search engines what the target is about.