Tooltips

Overview

Tooltips are often used to convey information. However, tooltips are rarely appropriate, and their misuse can result in a myriad of accessibility issues. Always consider not using a tooltip for an improved user experience.

Why?

• Tooltips are hidden by default making it easy to miss, so they should never be used to convey critical information.
• Tooltips are never accessible on mobile devices.
• Tooltips should never be set on non-interactive elements (for example, div, span, p), and should only ever be set on interactive elements (for example, button, a). Tooltips on non-interactive elements are not accessible to keyboard users and screen reader users.

Guidelines

For designers

• Reserve tooltips for components like icon buttons.
• Keep your tooltip text minimal.
• Only include tooltips on other components as a last resort.
• Never include tooltips on non-interactive components (div, span, p).

Do

Use a tooltip to give a text label to an icon button

Don’t

Don't use tooltips on non-interactive elements

Annotations

If you have an appropriate tooltip in your design, annotate the tooltip carefully with the preferred type (whether it's a label or description) to ensure proper semantics.

For developers

If you come across a design or a page with a tooltip on a static element (for example, div, span, p), remove it. Consult a designer for an alternative way of conveying the information.

If you determine that tooltips are appropriate for your use case, make sure to carefully follow guidelines set in Primer ViewComponents: Tooltip component.

Alternatives to tooltips

See the examples of alternatives to tooltips.