Tooltip

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Tooltip displays brief, contextual information when users hover over or focus on an element, providing helpful hints without cluttering the interface. It provides a simple, accessible way to display supplementary information that appears on hover or focus. Built on Radix UI's Tooltip component, it ensures consistent tooltip behavior across the interface with automatic positioning, keyboard accessibility, and screen reader support.

Props

Name	Type	Default	Description
`children`	`ReactNode`	—	Trigger and {@link TooltipContent }.
`announce`	`boolean`	`true`	Whether assistive technology is told about the tooltip. `false` is for a tooltip that repeats text the trigger already contains, such as the full text of a clipped label: the trigger gets no `aria-describedby` and the surface is `aria-hidden` with no `tooltip` role, so a screen reader reads the text once, from the trigger. Leave it `true` whenever the tooltip adds information the trigger's own content does not carry.
`closeDelayMs`	`number`	—	Delay before closing after leave, in milliseconds. Defaults to the kernel hover close delay.
`closeOnPress`	`boolean`	`true`	Whether pressing the trigger with a mouse or pen dismisses the tooltip. A press usually starts the action the tooltip describes, such as opening a dialog, and a tooltip that opens or stays open over that action is noise. A pending open is cancelled too, and the tooltip stays closed until the pointer leaves and returns. Keyboard focus is unaffected.
`defaultOpen`	`boolean`	—	Initial open when uncontrolled.
`disabled`	`boolean`	—	Disables hover and focus scheduling.
`onOpenChange`	`((open: boolean, details: ChangeDetails<ChangeReason>) => void)`	—	Called when open changes from hover, focus, Escape, or blur.
`open`	`boolean`	—	Controlled open state.
`openDelayMs`	`number`	—	Delay before opening, in milliseconds. Defaults to the kernel hover open delay.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Use for simple text hints that appear on hover.

Control where the tooltip appears relative to its trigger element.

Display the tooltip above the trigger element (default).

Display the tooltip to the right of the trigger element.

Display the tooltip below the trigger element.

Display the tooltip to the left of the trigger element.

Control how the tooltip aligns with its trigger element.

Start Alignment

Align the tooltip to the start of the trigger element.

Center Alignment

Align the tooltip to the center of the trigger element (default).

End Alignment

Align the tooltip to the end of the trigger element.

Use React nodes for tooltips with formatted content.

Add tooltips to icon buttons for clarity.

Provide additional context for text elements.

Show full text in a tooltip when display text is truncated.

Conditionally disable tooltips based on application state.

When disabled, the tooltip doesn't appear and only the children are rendered.

Control tooltip visibility programmatically.

Wrap elements that don't support event handlers.

The tooltip automatically handles event delegation for wrapped elements.

Wrap disabled elements to show tooltips explaining why they're disabled.

Disabled elements don't emit pointer events, so wrapping them in a span enables tooltip functionality.

Multiple Tooltips

Use multiple tooltips in close proximity.

Handle longer tooltip content appropriately.

Tooltips automatically wrap long content, but keep tooltip text concise for better user experience.

Add tooltips to table cells for additional context.

Combine tooltips with icons for informative UI elements.

Stacking above popovers

--z-index-tooltip and --z-index-popover share the same token value. .pr-tooltip therefore uses calc(var(--z-index-tooltip) + 100) so a tooltip on a control inside a popover always paints above the popover surface. Do not raise the --z-index-tooltip token itself for this — the .pr-z-index-tooltip utility is reused by snackbars and other chrome that must stay in the shared band.

Positioning Considerations

Tooltips automatically adjust position when there's insufficient space.

Radix UI automatically flips the tooltip to the opposite side if there isn't enough space in the specified direction.

Tooltip / Usage

Accessibility / Keyboard Support