Tooltip

v1.0.0 | View in Storybook

​

When to use

• Clarification: Use Tooltips when there’s a need to explain UI elements that may not be self-explanatory.
• Icons Buttons: When controls use icons without labels, or the label needs more clarity, a Tooltip can provide context or detail.
• Short instructions: Use Tooltips for brief instructions or details that would otherwise clutter the main interface if shown all the time.
• Non-critical info: Tooltips are best used for supplementary or optional information that does not require immediate attention.

​

When to use something else

• Long copy: use inline text, side panels, or Alert—not a Tooltip.
• Critical or frequently needed information: surface it in the layout or Dialog, not only in a tooltip.
• Redundant text: don’t mirror the visible Button label in the tooltip.

​

Behavior

• On hover: The Tooltip should appear when the user hovers over or focuses on the trigger element and disappear when the hover/focus is removed.
• On focus (accessibility): Tooltips should also activate when the user focuses on an element using the keyboard (e.g., pressing Tab to navigate between buttons). This ensures that screen reader users and keyboard-only users can interact with the Tooltips.
• Delay: Introduce a slight delay before showing the Tooltip (e.g., 200ms-500ms).

​

Often used with

Icon-only Button, Toggle group segments, compact Toolbar items—always with an accessible name on the trigger, not only the tooltip.

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

With button variants

Attach tooltips to different button variants to show how supplementary text works across primary, secondary, and ghost triggers.

​

Position top

Place tooltips above the trigger when space below is limited or when the control sits near the bottom of the viewport.

​

Position right

Place tooltips to the right of the trigger when the control sits on the left edge of the layout or when vertical space is constrained.

​

Position bottom

Use bottom placement as the default when there is room below the trigger—for example, icon buttons in a toolbar or action row.

​

Position left

Place tooltips to the left of the trigger when the control sits on the right edge of the layout or when horizontal space is limited on the right.

​

All positions

Compare all four positions to choose placement that keeps the tooltip visible and does not obscure important content or fall outside the viewport.

​

With icons

Use tooltips on icon-only controls to provide the accessible name and brief context—for example, toolbar actions or compact toggle buttons.

​

Long content

Keep tooltip copy short in production—this example shows how longer text wraps, but prefer one or two lines for supplementary information only.

​

With offset

Adjust offset when the default gap between trigger and tooltip is too tight or overlaps adjacent UI—for example, near card edges or dense control groups.

​

Keyboard interactions

Ensure tooltips appear on keyboard focus as well as hover so screen reader and keyboard-only users receive the same supplementary information.

​

Default open

Use default open sparingly—for example, in onboarding or demos—to draw attention to a control; in normal use, tooltips should appear only on hover or focus.

​

Controlled state

Use a controlled tooltip when visibility must follow application logic—for example, guided tours, programmatic show and hide, or coordinated onboarding steps.

​

With delay

Add a short delay before showing tooltips to avoid flicker as users move the pointer across the interface—typically 200–500 ms for comfortable discovery.