Names, roles & states
A Tooltip Has No Text a Screen Reader Can Read
An element marked as a tooltip has no readable name, so screen reader users hear nothing — or just "tooltip" — where sighted people see a helpful hint.
aria-tooltip-nameWCAG 2.0Introduced in WCAG 2.0.Level AA — the minimum. Missing it blocks people outright.
- Status
- SeriousSerious — Significant friction, or information that is lost.CurrentScanners run this rule today.
- Owner
- DesignDevContentTest
- Audit
- Automated+ManualA scanner finds it; a person confirms the fix.
Why it matters
A tooltip is a small pop-up hint that explains a button, icon or field. Screen readers read out its text, called its "accessible name".
If the tooltip has no text, or its text is hidden from screen readers, the hint is lost. Icon-only buttons often rely on tooltips, so people may not know what the button does.
Who it affects
| Who | What they experience | Impact |
|---|---|---|
| Screen reader users | They hear silence or just "tooltip", and miss the hint that explains the control. | High impact |
| Low-vision users (magnification) | Those using a screen reader lose the hint. Those using zoom can still read the text if it shows on screen. | Partial impact |
Business & product impact
| Area | Why | Impact |
|---|---|---|
| Legal | It fails WCAG 4.1.2 at Level A, the minimum, and the matching EN 301 549 clause. Complaints under Australia's Disability Discrimination Act point to WCAG 2.2 AA. | High impact |
| Conversion | If an icon button's only label is a broken tooltip, people may skip a key action like "Save" or "Share". | Moderate impact |
| SEO | No real search benefit — don't sell it as one. | Low impact |
| Brand trust | Unlabelled controls make a product feel careless to screen reader users. | Moderate impact |
| Cost to fix | Usually quick. Fix it once in the shared tooltip component and every use improves. | High impact |
Fixing it in code
A tooltip with its text in an attribute that isn't read
Don't
<button aria-describedby="tip1">✎</button>
<div role="tooltip" id="tip1" data-text="Edit profile"></div>A screen reader says: “Button”
Do
<button aria-describedby="tip1" aria-label="Edit">✎</button>
<div role="tooltip" id="tip1">Edit profile</div>A screen reader says: “Edit, button, Edit profile”
Text inside the tooltip gives it a name screen readers can read.
A tooltip with its text hidden from screen readers
Don't
<div role="tooltip" id="tip2">
<span aria-hidden="true">Copy link</span>
</div>A screen reader says: “(nothing)”
Do
<div role="tooltip" id="tip2">
<span>Copy link</span>
</div>A screen reader says: “Copy link”
Removing aria-hidden lets screen readers reach the tooltip's text.
Designer's handoff note
Write the tooltip text for every icon in your designs. Also note the button's own label — don't rely on the tooltip alone.
Keep tooltip text short and plain, like "Edit profile".
Quick test
Tool
NVDA (opens in a new tab) (free on Windows)
Checklist
- Pass
- You hear the same hint text you see in the tooltip.
- Fail
- You hear only "button", or nothing about the hint.
Check these at the same time
- A custom button, link or menu item has no name
aria-command-name - Hidden content can still receive keyboard focus
aria-hidden-focus - A button has no name a screen reader can say
button-name - A link has no text a screen reader can read
link-name
What a green scan still misses
A scanner checks that the tooltip has some text. It can't tell if the text is clear, correct, or matches what's on screen.
Reference
- Rule ID
aria-tooltip-name- Raised by
- axe-core: “ARIA tooltip nodes must have an accessible name”
- WCAG
- 4.1.2 Name, Role, Value (opens in a new tab) · Level A · since WCAG 2.0
- Other standards
- EN 301 549 9.4.1.2
- Last reviewed
- 14 October 2026