Tooltip

Displays contextual information in a popup anchored to a trigger element. For attaching a tooltip to an external ref (without wrapping children), use the `useTooltip` hook directly.

Examples

Text Trigger

Hover for details

Helpful tooltip text

<Tooltip
  content="Helpful tooltip text"
  placement="above"
  alignment="center"
>
  Hover for details
</Tooltip>

Button Trigger

Hover me

Helpful tooltip text

<Tooltip {...args}>
  <Button label="Hover me" />
</Tooltip>

Placements

Above

Above

Below

Below

Start

Start

End

End

<div style={{display: 'flex', gap: '1rem', padding: '4rem'}}>
  <Tooltip content="Above" placement="above">
    <Button label="Above" />
  </Tooltip>
  <Tooltip content="Below" placement="below">
    <Button label="Below" />
  </Tooltip>
  <Tooltip content="Start" placement="start">
    <Button label="Start" />
  </Tooltip>
  <Tooltip content="End" placement="end">
    <Button label="End" />
  </Tooltip>
</div>

Alignments

Start

Aligned to start

Center

Aligned to center

End

Aligned to end

<div style={{display: 'flex', gap: '2rem', padding: '4rem'}}>
  <Tooltip alignment="start" content="Aligned to start" placement="above">
    <Button label="Start" />
  </Tooltip>
  <Tooltip alignment="center" content="Aligned to center" placement="above">
    <Button label="Center" />
  </Tooltip>
  <Tooltip alignment="end" content="Aligned to end" placement="above">
    <Button label="End" />
  </Tooltip>
</div>

Disabled

Hover for details

Helpful tooltip text

<Tooltip
  content="Helpful tooltip text"
  placement="above"
  alignment="center"
  isEnabled={false}
>
  Hover for details
</Tooltip>

Rich Content

Help

Keyboard shortcutPress Cmd+K to open the command palette

<Tooltip
  {...args}
  content={
    <div style={{display: 'flex', flexDirection: 'column', gap: 4}}>
      <Text type="label">Keyboard shortcut</Text>
      <Text color="secondary" type="supporting">
        Press Cmd+K to open the command palette
      </Text>
    </div>
  }>
  <Button label="Help" />
</Tooltip>

With Use Tooltip Hook

Hover this badge

Attached via useTooltip hook

function UseTooltipHookStory(): React.JSX.Element {
  const handleShow = useCallback(() => {}, []);
  const handleHide = useCallback(() => {}, []);
  const tooltip = useTooltip({
    placement: 'above',
    onShow: handleShow,
    onHide: handleHide,
  });

  return (
    <>
      <Badge
        aria-describedby={tooltip.describedBy}
        color="info"
        label="Hover this badge"
        ref={tooltip.ref}
      />
      {tooltip.renderTooltip('Attached via useTooltip hook')}
    </>
  );
}

<UseTooltipHookStory />

Hover Indication

Underlined on hover

Helpful tooltip text

<Tooltip
  content="Helpful tooltip text"
  placement="above"
  alignment="center"
  hoverIndication="always"
>
  Underlined on hover
</Tooltip>

Focus Trigger Always

Focus me (non-interactive element)

Shown on focus even though div is not natively focusable

<Tooltip
  content="Shown on focus even though div is not natively focusable"
  focusTrigger="always">
  <span role="button" style={{padding: '0.5rem 1rem'}} tabIndex={0}>
    Focus me (non-interactive element)
  </span>
</Tooltip>

Focus Trigger Never

Hover only

Only shown on hover, never on focus

<Tooltip content="Only shown on hover, never on focus" focusTrigger="never">
  <Button label="Hover only" />
</Tooltip>

API

Tooltip

Displays contextual information in a popup anchored to a trigger element. For attaching a tooltip to an external ref (without wrapping children), use the `useTooltip` hook directly.

Prop	Type	Default	Description
alignment	"center" | "start" | "end"	'center'	Cross-axis alignment of the tooltip relative to the anchor.
children*	ReactNode	—	Element(s) that the tooltip is anchored to.
className	string	—	Additional CSS class names applied to the wrapper.
content*	ReactNode	—	Content rendered inside the tooltip popup.
contentStyle	CSSProperties	—	Inline styles applied to the tooltip content area.
data-testid	string	—	Test ID applied to the wrapper.
delay	number	200	Delay in milliseconds before the tooltip appears.
focusTrigger	"auto" | "always" | "never"	'auto'	How focus interactions trigger the tooltip.
hideDelay	number	0	Delay in milliseconds before the tooltip hides after leaving.
hoverIndication	'always' | 'auto' | 'never'	'auto'	Dashed underline display for tooltip triggers.
isEnabled	boolean	true	Whether the tooltip can be shown.
isHiddenOnPress	boolean	true	Whether pressing or clicking the trigger dismisses the tooltip. Set to false for triggers that remain engaged while pressed, such as a drag handle.
placement	"start" | "end" | "above" | "below"	'above'	Preferred placement of the tooltip relative to the anchor.
ref	Ref<HTMLDivElement | HTMLSpanElement>	—	Ref forwarded to the wrapper element.
style	CSSProperties	—	Inline styles applied to the wrapper.