Create custom and accessible tooltip

How to create a custom tooltip with JavaScript, HTML, and CSS that is accessible and styled the way you want.

A tooltip is a widely used feature across the web. Hundreds of different approaches and implementations. The ARIA Authoring Practices Guide (APG) defines the tooltip in the following way:

A tooltip is a popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. It typically appears after a small delay and disappears when Escape is pressed or on mouse out.

Another definition of tooltip from Mozilla Developer Network:

A tooltip is a contextual text bubble that displays a description for an element that appears on pointer hover or keyboard focus.

The document Pop Up API (Explainer) indicates that creating a tooltip, contrary to popular belief, isn’t an easy task.

How do you create a tooltip in HTML?

Let’s take on the challenge of creating a custom tooltip. Before everything, let’s first define the basic requirements for the tooltip.

• Tooltips should only be displayed for interactive elements.
• Must be positioned automatically to fit into the visible area.
• Tooltips must be discoverable and readable with a mouse, other pointer devices, keyboard, screen reader, zoom software, and any other assistive technology.
• Must be triggered by both focus and hover events.
• We’ll use aria-describedby (aria-labelledby can be used as well) to associate the UI control with the tooltip content. Note: avoid aria-haspopup and aria-live.
• Should allow the use of HTML. Note: Use only without interactive elements inside.
• Follow WCAG technique Making content on focus or hover hoverable, dismissible, and persistent that relates to Success Criterion 1.4.13: Content on Hover or Focus.
• Use prefers-reduced-motion to customize the animation (fade in and fade out) based on the user’s settings. See also Responsive Design for Motion (WebKit Blog) that includes vestibular motion trigger examples.

Notes

Requirement: reduce motion using CSS prefers-reduced-motion

Most operating systems, and by extension, browsers, through prefers-reduced-motion media query, allow us to reduce motion where the user can stop or reduce the movement of some elements on the screen. For those who suffer from vertigo or motion sickness, this feature is extremely helpful. Here is an example from the Mac OS:

How to make tooltips with only CSS?

There are many articles like How To Make Tooltips With Only CSS, Pure CSS Tooltip | How To Create Tooltips using CSS3 or Tooltips with CSS Only that describes how to make a tooltip without JavaScript.

However, while it is possible to create a tooltip that works without JavaScript then the drawback is that you can’t set automatically the tooltip position that must fit into the visible area. See the example when the button is close to the top of the page:

Real code example

Let’s see how a tooltip could be implemented.

1. Go to SiteLint Platform Tools page.
2. Scroll down to the footer (very bottom of the page).
3. See the tooltip next to the buttonShare

How a screen reader works with our tooltip (video)

Questions related to the tooltip

Do screen readers read tooltips?

They do read the tooltip, but it all depends on the implementation and what’s being exposed to the screen reader. If the tooltip is created correctly, then they should read the tooltip content. Just like any other HTML content.

How does a user access a tooltip?

Through a device type like mouse, pen, touch.

Why is it called a tooltip?

Because they are typically used to provide contextual and usage information to the many tools in an application without having to study extensive manuals and other documentation, they are known as tooltips.

Should you put links in tooltips?

Avoid using any links or other actionable elements. Use HTML to add extra semantics like <strong>. Simple text explanations should be included in tooltips. It is no longer a tooltip if you need any links, buttons, or more complex HTML inside of it.

Native, built-in popover

A better approach would be to use the native, built-in popover feature. Mozilla Developer Network describes it as:

The Popover API provides developers with a standard, consistent, flexible mechanism for displaying popover content on top of other page content. Popover content can be controlled either declaratively using HTML attributes, or via JavaScript.

<button type="button" popovertarget="mypopover">Toggle the popover</button>
<output id="mypopover" popover>Popover content</output>

Note that native popovers do not work everywhere yet. So, check the browser compatibility table or provide fallback.

Native popover example