ARIA tooltips must provide accessible text descriptions
Content available in English only.
Accessibility isn’t just about avoiding violations — it’s about ensuring that everyone can use your product with confidence. This guide explains each rule’s intent, highlights common issues, and shows how to fix them according to WCAG and the European Accessibility Act (EAA).
These guidelines do not replace the official WCAG standards. They’re concise, developer-focused notes to help you identify and fix issues effectively.
Every tooltip must have descriptive text and be referenced by its trigger.
Why this matters and how to fix it
Why this matters
Tooltips without accessible text or proper association are invisible to screen reader users. This prevents users from accessing supplemental information, leading to an unequal experience, especially for icon-only controls.
How to fix this issue
Ensure every element with `role="tooltip"` contains meaningful text and that its trigger element references it using `aria-describedby`. The tooltip must appear on hover or keyboard focus and hide when focus or hover leaves. Avoid using the HTML `title` attribute, as it is inconsistently announced by assistive technologies.
Developer guidance
A tooltip supplements, but never replaces, a control’s accessible name. Each tooltip must have a clear trigger that can be focused with a keyboard. Follow the WAI-ARIA 1.2 Tooltip Pattern and confirm correct associations with a screen reader. Tooltips should not be used to display essential instructions or error messages.
Code examples
Incorrect Implementation
<button>Info</button>
<div role="tooltip"></div>Correct Implementation
<button class="trigger" aria-describedby="tip1">Info</button>
<div role="tooltip" id="tip1">Provides additional details about this option.</div>Real-World Examples
Before
<button class="icon-help"></button>
<div role="tooltip"></div> <!-- Screen reader announces nothing -->After
<button class="trigger" aria-describedby="helpTip">Help</button>
<div role="tooltip" id="helpTip">Explains the purpose of this control.</div>CSS Example (Guidance)
.tooltip { display: none; position: absolute; background: #333; color: #fff; padding: 4px 8px; border-radius: 4px; }
.trigger:focus + .tooltip,
.trigger:hover + .tooltip { display: block; }Manual testing
- 1. Identify all elements with `role="tooltip"` and their triggers.
- 2. Verify that each tooltip contains meaningful, descriptive text.
- 3. Ensure the trigger references the tooltip using `aria-describedby`.
- 4. Tab to the trigger and confirm the tooltip text is announced by a screen reader.
- 5. Hover or focus on the trigger to verify the tooltip appears visually.
- 6. Confirm the tooltip hides when focus or hover leaves.
Trusted by organizations across Europe working toward WCAG and EAA conformance