Here at Eleven Ways, we often get asked for “the correct, accessible tooltip pattern”. Building accessible tooltips is a minefield — especially when you mix in rich content and screen reader quirks. Let’s examine the issues and go in search of a tooltip pattern that truly covers all our bases.
Here at Eleven Ways, we often get asked for “the correct, accessible tooltip pattern”. Building accessible tooltips is a minefield — especially when you mix in rich content and screen reader quirks. Let’s examine the issues and go in search of a tooltip pattern that truly covers all our bases.
aria-describedby pattern is the best starting point for simple controls.Read on to understand how we came to these conclusions…
There is no native tooltip component in HTML, but we can define a functional pattern based on common implementations and industry research. We distill this into a pattern consisting of:
A strict definition calls for plain, descriptive text only but we frequently see implementations with formatting or links. So let’s expand our criteria:
Considering accessibility requirements, the tooltip implementation by Deque University provides an excellent baseline. Its principal attribute is the use of aria-describedby, a method favoured by almost every implementation aiming for an accessibility standard.
Key features of this implementation:
aria-describedby. This ensures the tooltip is read when the element receives focus.CSS display:none, visibility:hidden, or the HTML hidden attribute) and is still found and read by assistive technology.role="tooltip".To test screen reader behaviour for our baseline standard, we can use the tooltip demo page by Deque University.
In addition, we also created our own demo page, to test these real-world use cases:
We tested these using NVDA, Narrator, VoiceOver (macOS/iOS), and Android TalkBack.
From Webaim Screen Reader User Survey #10 Results:
"NVDA is again the most commonly used screen reader at 65.6% of respondents outpacing JAWS at 60.5%. Narrator ... is commonly used by 37.3% of respondents ... Respondents with disabilities (72.4%) used iOS devices at a higher rate than those without disabilities (56%)".
aria-label)of the tooltip as well as the tooltip itself are readaria-label first (’Tooltip : `), followed by the content textOur testing revealed several critical gaps where standard implementations fail to meet user needs:
aria-label (the "Tooltip:" prefix) when navigating with arrow keys.Discrepancy between NVDA’s Focus and Browse modes can be attributed to inherent verbosity settings, as Adrian Roselli notes in the comments of his article on aria-describedby. While users can often tweak these settings, we want to ensure tooltips in text blocks are read by default. We found no success in tinkering with these settings to resolve the issue.
We do not currently have a "clean" fix, as our attempts kept adding more complexity or confusion.
Fixing the aria-label: To ensure the "Tooltip:" prefix is heard, you can add a visually hidden span within the tooltip text.
The CSS:
.sr-only {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border-width: 0;
}
The JS:
data-tooltip="<span class=\"sr-only\">Tooltip: </span>This is the tooltip content"The "Double Duty" Label: For triggers within blocks of text, the only viable workaround we found, was to hijack the trigger's label to inform the user that a tooltip is available, along with its ‘standard’ function. In doing so, we are at risk of losing the distinction between the Action (navigating somewhere) and the extra Information (the tooltip content).
<!-- For a button --><button aria-label="funambulist - focus or hover to get the definition of 'funambulist'" data-tooltip="This tooltip contains the definition of the word funambulist">funambulist</button><!-- For a link --><a href="https://some-site" aria-label="funambulist - focus or hover to get important information about an article on funambulists" data-tooltip="This tooltip contains important context about a linked article">funambulist</a>The failure of links with aria-describedby in Microsoft Narrator appears to be a bug. While the attribute is technically allowed on any element with an ARIA role, Narrator simply does not find the description for links.
Looking at historical data about aria-describedby from A11ySupport.io and tests by Adrian Roselli, aria-describedby support in Narrator has been broken for years. While button support was eventually resolved, link support remains broken four years later.
But given that Narrator is used by 37.3% of respondents, we still want to account for it.
tabindex, but these failed. The obvious reason is that issue is in Narrator’s implementation (or Microsoft Speech API), not the browser's interpretation.title or aria-label on the link itself is not recommended. Screen readers that do support aria-describedby would read the text twice, and these properties are meant to provide the link's name, not a supplementary description.The reason that links can not be reached, is simply because of how aria-describedby is implemented in browsers. The trigger needs focus to make the description appear/read by screen readers. Once that focus is gone (eg. by moving it to a nested element), the connection is severed. It makes sense now, why aria-describedby is meant to only contain plain text.
Technically, if tooltip content is extensive or contains useful semantics, aria-details is a more appropriate attribute. However, aria-details was not read out by our screen readers, so it’s not a viable option.
In our tests, markup called via aria-describedby was displayed visually without issue. How screen readers handle inline markup (like <strong>) or special characters depends on the specific reader and the user's individual verbosity settings. For example, NVDA announced emojis out of the box, whereas VoiceOver did not. Consequently, we’re treating "markup support" as a non-issue.
Since aria-describedby fails in several cases, can we build a tooltip without it? The answer is: "It depends on which criteria you are willing to let go of".
To recap, we wanted to address our original failures:
While we are looking into alternatives, we can also take a look at some "nice-to-have" improvements:
The solution that most closely aligns with this behaviour is a non-modal dialog. (Note: "Modal" refers to the state of blocking the rest of the page, while "Dialog" refers to the component itself). However, dialog patterns don’t provide a method for a screen reader to read the information out, when the dialog opens.
We investigated 2 possible avenues to resolve this but hit major obstacles on both:
aria-live is problematic because announcements cannot be easily dismissed, interrupting the user's flow. It also requires the region to be present in the DOM at page load to be detected, creating potential headaches for Javascript-oriented solutions and frameworks which are very much on the forefront of web development at the moment.For sake of completion, we created a proof-of-concept to test the hover behaviour (keeping in mind it fails WCAG 3.2.1 On focus).
There is no one-size-fits-all solution, you must choose based on your specific use case.
Our first recommendation is to place information in an easy-to-reach way near the element. For input fields, adding a description below the field and using aria-describedby is the most straightforward method.
For most scenarios, a tooltip based on aria-describedby (as exemplified by Deque) remains the best option.
If you do want to use them on links, you’ll have to wait until Microsoft Narrator is fixed.
If you want to help move that forward, file an issue using the Microsoft Feedback Hub. The more folks complain about it, the better chance we have at getting an update that resolves the problem.
If your tooltip requires links, you must use a (non-)modal dialog triggered by a click or Enter key.
If you want to play around with an example, we’ve created a demo page for one here.
Understand though, that dialogs also have their own quirks, which we won’t get into here. For example, Adrian Roselli has an excellent article on dialog focus.
To add information to words in a paragraph, we recommend accessible footnotes. Our preferred pattern is based on research by Nicki Bright, which uses "back links" and visually hidden text for clarity.
You can it out on our demo page or take a look at this code example:
<p>
A bit of text that needs a footnote
<a id="footnote-01-link" href="#footnote-01">
<sup>[1] <span class="sr-only">Footnote details</span></sup>
</a>.</p>
<ol>
<li id="footnote-01">
The footnote text goes here
<a href="#footnote-01-link" aria-label="Back to content">↩</a>
</li></ol>At Eleven Ways, we believe that accessibility means understanding how real people interact with technology. Tooltips may seem like only a small part of the UI, but the impact of a broken implementation means a dead-end for the users that rely on that information. By choosing the right pattern for the right context, we can build a web that truly works for everyone.
For further reading on the foundations of accessible tooltips, we recommend:
Twenty Walloon municipalities have refused to sign Esenca’s Municipal Charter for the Inclusion of People with Disabilities. We checked the accessibility of their homepages.
Star rating systems seem so straightforward, don't they? A quick click, and your feedback is submitted. Easy peasy! But beneath that simple surface lie a couple of tricky accessibility questions that are crucial for making sure everyone can use them effectively.