Custom Tooltips

Examples of accessible, custom tooltips that can be used to reveal a description or used as a means to reveal an accessible name (then not a tooltip) of an element.

See the source on GitHub

Tooltips primer


A tooltip is meant to provide short, but non-essential, information to help further describe the element it is associated with.

In native HTML the title attribute can be used to provide an element with a tooltip. For example, hovering over: this test link.

The problem with HTML tooltips is that they are often not discoverable unless someone is specifically using a mouse to interact with content. Some browsers, like IE11 and pre-Chromium Edge (hopefully post Chromium as well), expose HTML tooltips on focus of an element. However, this still means that elements that cannot (and often times should not) receive focus will still have tooltips that will likely be inaccessible to people not using a mouse.

Custom Tooltips

To create a custom tooltip, we should look to the ARIA specification for role=tooltip.

The following are criteria to follow when building a custom tooltip:

  • The tooltip is invoked upon hover or focus of the element which the tooltip describes, after a short pause.
  • The tooltip should be referenced by the element that it is associated with by use of aria-describedby.
  • The tooltip itself should not be focusable, or contain elements which are focusable. Contents announced by aria-describedby are flattened to a single text string. Any nested semantics will be lost, if not completely ignored. E.g. a "link" or "heading" will not be announced, only their text strings. A list within a tooltip may be completely ignored by certain assistive technologies when announced as the flattened string.
  • The tooltip is dismissed after the element which invoked the tooltip has been blurred.
  • The tooltip should dismiss upon mouse hover leaving the element which invoked the tooltip, unless the mouse is moved to hover the tooltip itself, per WCAG success criterion for 1.4.13: Content on Hover or Focus. If mouse hover is no longer over the initial element that invoked the tooltip, nor the tooltip itself, then the tooltip is dismissed.
  • A tooltip is dismissible by use of the Esc key to mimic a native HTML tooltip's functionality, as well as also meeting WCAG 1.4.13.

Custom accessible name "tooltips"

While not following the semantic definition of a tooltip, there are times where a design will use a tooltip-like popup to display the accessible name of an element.

Though not the ideal manner to do so, there are situations where even the title attribute can be used to provide an element its accessible name. Therefore, this script will also allow for the "tooltip" to display the accessible name of an element, if designated to do so.

If used in this manner, the "tooltip" will not receive a role=tooltip. It will be referenced from the associated trigger by aria-labelledby rather than aria-describedby since it's providing the name, and not a description.

A native test

An input with a title attribute. In this instance, the title provides the input with its accessible name, due to the input not having a name from more optimal sources.

Tooltip on a text fields

Hard coded fallback.

A user name can either be your phone number,
or your email address.

As this is the Internet, an apostrophe is not allowed.

Change your name.

Not really sure why we need this...

Tooltip generated from title attribute

Tooltip on buttons and links

Tooltip hard coded in DOM

Deleting your account will mean it's deleted.

Tooltip hard coded in DOM

You can try to visit our online store External link. to see if we have what you need.

Tooltip created from data-tooltip-content attribute

Tooltip created from data-tooltip-content attribute

How to make marvelously magnificent marbled muffins

Tooltip generated from title attribute