Components

Tooltip

Overview

When to use

Use tooltips to add a small amount of information to an element. For example:

• help people understand the meaning or purpose of icons.
• show non-essential supporting information.

When not to use

Do not use tooltip for information that is crucial for completing a task. Use hint text that is always visible and accessible for vital information. Tooltips have low discoverability and have usability issues on devices without hover interactions.

Do not include interactive elements such as links or buttons inside a tooltip. Interactive elements in tooltips are inaccessible for some users and are hard to use for all users since tooltips do not receive focus.

Do not use tooltips to display error or status messages.

Principles

The tooltip can only contain text and should not be used to hide important information.

Behavior

Tooltips appear on hover and focus.

By default, tooltips have a 200ms entry delay when hovering over an object. This is to ensure that the UI isn't constantly showing tooltips when a user is moving their mouse over the page. The default exit delay is set to 100ms.

When navigating by keyboard, tooltips appear immediately on focus and disappear also without delay when navigating away from the element with the tooltip. Pressing Esc dismisses the tooltip without moving focus, whether it was triggered by hover or focus.

Trigger examples

Size

The maximum width of a tooltip is set to 240px. Longer content is wrapped to multiple lines.

Placement

Tooltips should always be placed in a way that does not cover related content that is essential to the user’s tasks. Tooltips should not bleed off page or appear behind other content.

For tooltips that are inline with other text, like a definition tooltip, do not obstruct words to the left and right of the trigger word.

Usage

Usage guidelines

Content

Keep the content of the tooltip as clear and concise as possible.

Do

Don't

Avoid restating visible UI text.

Do

Don't

Placement

For tooltips that are inline with other text, like a definition tooltip, do not obstruct words to the left and right of the trigger word.

Do

Don't

Interactive elements

Avoid placing interactive elements, such as buttons and links, inside tooltips.

Don't

Accessibility

Keyboard

• The tooltip shows when its trigger receives focus and hides when focus leaves it.
• Enter or Space on the text trigger toggles the tooltip. On a button trigger they activate the button as usual; its tooltip is already shown by focus.
• Escape hides every open tooltip, including one opened by hovering an element that does not have focus.

Screen readers

The trigger references the tooltip through aria-describedby, and the tooltip element has role="tooltip". Its text is read as the trigger's description after the name, whether or not it is visible. The icon-button trigger is named by buttonLabel ("Muuda" by default) and its SVG is aria-hidden="true". The text trigger is a span with tabindex="0" so it can be focused.

Using the example

• A tooltip adds a short hint to something that already has a name. Never put the only label, essential instructions or interactive content (links, buttons) inside it.
• Every tooltip id must be unique, and the trigger's aria-describedby must match it.
• Prefer a real button or link as the trigger. Use the focusable span only for inline terms such as abbreviations.
• Change the default buttonLabel to describe what the button does.

Known limits

The tooltip hides when the pointer leaves the trigger, so it cannot be hovered itself (WCAG 1.4.13 "hoverable"). Keep tooltip text short enough to read without moving the pointer onto it.