A tooltip gives an icon-only button a short name when the user hovers it or moves keyboard focus to it. Esc hides it.
Every example on this page is the real component, not a picture. Figma: Tooltip.
An icon button with a tooltip. Pick any of the 11 Figma types in Small or Large. “Shown” forces the tooltip open for inspection; “Live hover” lets you hover the button yourself, or Tab to it: it also shows on keyboard focus.
Automatic alignment applies to Bottom and Top (centered) only; the other types are always manual.
Left Top and Right Top exist in Small only in Figma, so Small is shown.
This demo provides a preview of the component’s functionality and styles. For the complete experience, including version details, controls, and API documentation, visit Storybook.
Tooltips are typically documented as part of the components they belong to, rather than as standalone components. The only exception is the Definition Tooltip, which has its own documentation.
They provide additional information when a user hovers over a UI element and should only be used when necessary to offer quick context without cluttering the interface.
This documentation has three pages. Examples & Guidelines (this page) shows when and how to use a tooltip. Specifications holds the values: tokens, sizes, spacing and requirements. Code shows how to add a tooltip to a page.
Most components, such as Icon Buttons, Icon Tabs, Sliders, and Copy Buttons, already include built-in tooltips. In most cases, there is no need to add a tooltip separately. While customization is possible, it is generally not recommended.
Use tooltips to:
A Definition Tooltip is used to explain terms or provide additional help within text. It is especially useful for labels, words in paragraphs, and compact interfaces such as data tables, where adding extra icons could create visual clutter.
Do not use tooltips for important information that users need to complete a task. Since tooltips disappear when users move away from the element, they can be easily missed. Use always-visible helper text instead, especially for important instructions or required fields.
Do not place interactive elements, such as buttons, links, or images, inside a tooltip. Tooltips cannot receive focus and may be difficult or impossible for some users to interact with.
If users need to interact with additional content, use a Toggletip (TBA) instead. Toggletips support proper focus management and keyboard navigation, providing a more accessible experience for all users.
| The element… | Use |
|---|---|
| is an icon button with no visible text | Tooltip |
| has a visible label | No tooltip |
| needs more than a few words | Inline notification or help text |
| must work on touch | Not a tooltip: it needs hover |
aria-label.To be added. The Definition Tooltip has its own anatomy, which is not documented yet.
A tooltip comes in 11 types: eight with a beak at the start, center or end of one edge, two with a beak 16px from the top of a side, and Body, which has no beak and no placement. Top and Bottom are automatic by default: they stay inside the viewport and flip when there is no room (see Behavior). The other types are always manual.
tooltip--toptooltip--top-starttooltip--top-endtooltip--bottomtooltip--bottom-starttooltip--bottom-endtooltip--righttooltip--lefttooltip--right-starttooltip--left-starttooltip--bodyTo be added. The Definition Tooltip has its own variants, which are not documented yet.
A tooltip has two sizes. Small is the default. Left Top and Right Top exist in Small only.
The default size, for icon buttons in toolbars and table rows. 14/20 text, 8px 16px padding.
Add tooltip--lg. 18/26 text, 12px 16px padding.
The tooltip container can be aligned to the start, center, or end of its trigger element. This helps keep the tooltip visible and prevents it from covering important content.
The trigger and caret should be vertically aligned to clearly show their connection, especially when multiple interactive elements are placed close together.
By default, tooltips use auto placement. When opened, they automatically adjust their position to stay within the viewport and avoid being cut off.
Tooltips can also be positioned on the top, right, bottom, or left side of the trigger element. Always ensure the tooltip remains visible and does not cover content that is important for the user’s task.
For definition tooltips, avoid covering the surrounding text, especially the words immediately before and after the trigger word.
When active, the tooltip should appear above other content and remain fully visible without being clipped by nearby components or extending beyond the viewport.
A tooltip is one line when the text fits. A longer text wraps at 280px, and a tooltip is never wider than the window minus 8px on each side. Keep the text to one to three words: a tooltip that wraps is a sign that the text belongs in helper text.
A tooltip is a dark box with white text: Surface 100 at 90% opacity, square corners, an elevation shadow and a 6px beak. It has no border and no icon. Token names and values are under Design Tokens in Specifications.
The tooltip shows when the user hovers the trigger. It fades in and out, and it ignores the pointer, so it never gets in the way (see the open point under Dismissal). The two states are listed under States in Specifications.
The tooltip also shows when the trigger gets keyboard focus (:focus-visible), so a keyboard user sees the name of an icon button. It does not show for the focus a mouse click gives. It hides when focus moves away. This follows Carbon, Spectrum and Polaris, and WCAG 2.2 1.4.13.
Top and Bottom tooltips are automatic. They are centered on the trigger. When a centered tooltip would leave the window sideways it aligns to the start or the end of the trigger instead, as shown under Layout & Appearance. When it opens with too little room on its side and more on the other, it flips above or below, beak included. A page with a sticky header counts the room from below the header. The other types are always manual.
The tooltip hides when the pointer leaves the trigger. With the global tooltip (data-tooltip) a mouse click on the trigger hides it too, so it does not cover the result of the click. On touch the tooltip shows on tap and hides on the next tap elsewhere.
A tooltip is a hover aid, not a way to deliver information. All requirements are listed under Accessibility Requirements in Specifications.
The tooltip shows when the trigger gets keyboard focus, and Esc hides it without moving focus. The trigger stays a normal button, reachable with Tab.
Give the trigger an aria-label with the same text as the tooltip. The tooltip itself is not announced, so the label is the only name a screen reader user gets.
Use a tooltip for a short name or hint on hover. Use a Toggletip (TBA) for content that is interactive or that users must reach by keyboard. Toggletips support proper focus management and keyboard navigation.