1. Components
  2. Overlay
  3. Tooltip

Tooltip

Tooltip displays a description of an element on hover or focus.

Aria docsAria API ReferenceReport an issueEdit this page
<Tooltip content="Add to library">
  <Button><PlusIcon /></Button>
</Tooltip>

Installation

npx dotui-cli@latest add tooltip

Usage

Use Tooltip to display a description of an element on hover or focus.

Best practices

  • Use tooltips to describe icons (e.g., icon buttons).
  • Keep the tooltip text minimal.
  • Never include tooltips on non-interactive components (div, span, p) because it will not be accessible for keyboard or screen reader users.
  • Don't place actions inside a tooltip

Options

Arrow

<Tooltip content="Add to library" arrow>
  <Button><PlusIcon /></Button>
</Tooltip>

Placement

The Tooltip's placement with respect to its trigger element can be adjusted using the placement prop. See the props table for a full list of available placement combinations.

<Tooltip placement="top" content="Add to library"><Button /></Tooltip>
<Tooltip placement="bottom" content="Add to library"><Button /></Tooltip>
<Tooltip placement="left" content="Add to library"><Button /></Tooltip>
<Tooltip placement="right" content="Add to library"><Button /></Tooltip>

Should flip

This option determines whether or not a tooltip should be able to switch sides when constrained by space.

<Tooltip shouldFlip={shouldFlip} content="Add to library">
  <Button><PlusIcon /></Button>
</Tooltip>

Offset

The offset is the distance between the end of the tip and the target.

<Tooltip offset={offset} content="Add to library">
  <Button><PlusIcon /></Button>
</Tooltip>

Container padding

To make sure that the tooltip will stay within certain boundaries (e.g., a browser window) it's possible to define a container and a container padding value to respect. The default value for this is 12 px.

<Tooltip containerPadding={containerPadding} content="Add to library">
  <Button><PlusIcon /></Button>
</Tooltip>

Delay

The delay duration (the time from when the mouse enters a tooltip trigger until the tooltip opens) and the close delay can be customised.

<Tooltip delay={delay} closeDelay={closeDelay} content="Add to library">
  <Button><PlusIcon /></Button>
</Tooltip>

Composition

For more flexibility, you can use the composition pattern to create a custom tooltip.

<TooltipRoot>
  <Button>Hover</Button>
  <TooltipContent>
    <p>Add to library</p>
  </TooltipContent>
</TooltipRoot>

API Reference

Tooltip

PropTypeDefaultDescription
content
React.ReactNode
-
The content of the Tooltip
isDisabled
boolean
-
Whether the tooltip should be disabled, independent from the trigger.
delay
number
700
The delay time for the tooltip to show up.
closeDelay
number
0
The delay time for the tooltip to close.
trigger
'focus'
-
By default, opens for both focus and hover. Can be made to open only for focus.
isOpen
boolean
-
Whether the overlay is open by default (controlled).
defaultOpen
boolean
-
Whether the overlay is open by default (uncontrolled).
triggerRef
boolean
RefObject<Element>
The ref for the element which the tooltip positions itself with respect to.
When used within a TooltipTrigger this is set automatically. It is only required when used standalone.
isEntering
boolean
-
Whether the tooltip is currently performing an entry animation.
isExiting
boolean
-
Whether the tooltip is currently performing an exit animation.
placement
Placement
'top'
The placement of the element with respect to its anchor element.
containerPadding
number
12
The placement padding that should be applied between the element and its surrounding container.
offset
number
10
The additional offset applied along the main axis between the element and its anchor element.
crossOffset
number
0
The additional offset applied along the cross axis between the element and its anchor element.
shouldFlip
boolean
true
Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
isOpen
boolean
-
Whether the element is rendered.
defaultOpen
boolean
-
Whether the overlay is open by default (uncontrolled).
arrowBoundaryOffset
number
-
The minimum distance the arrow's edge should be from the edge of the overlay element.
children
boolean
ReactNode | (values: TooltipRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode
The children of the component. A function may be provided to alter the children based on component state.
EventTypeDescription
onOpenChange
(isOpen: boolean) => void
Handler that is called when the overlay's open state changes.

Accessibility

Keyboard interactions

KeyDescription
Tab
Tabbing into an item that has a tooltip associated with it (e.g., a button icon) shows the tooltip.
Esc
Hides the tooltip

Last updated on 10/11/2024

DialogThemes