Tooltip

Doesn't open until your mouse stops moving.
Easy to animate enter and exit.
Sizable, positionable, unstyled or styled. Tooltip displays contextual information when hovering over an element. It waits for your mouse to stop moving before appearing, supports animations, and automatically stacks above other content.

Note that Tooltip doesn't render on native platforms.

Installation

Tooltip is already installed in @hanzo/gui, or you can install it independently:

npm install @hanzogui/tooltip

Anatomy

import { Tooltip } from '@hanzo/gui' // or '@hanzogui/tooltip'

export default () => (
  <Tooltip>
    <Tooltip.Trigger />
    <Tooltip.Content>
      <Tooltip.Arrow />
      {/* ... */}
    </Tooltip.Content>
  </Tooltip>
)

API Reference

Contains every component for the tooltip.

Prop	Type	Default	Required
children	React.ReactNode	-	✓
groupId	string	-	-
restMs	number	-	-
delay	number \| { open?: number; close?: number }	-	-
size	SizeTokens	-	-
placement	Placement	-	-
open	boolean	-	-
defaultOpen	boolean	-	-
onOpenChange	(open: boolean) => void	-	-
modal	boolean	true	-
stayInFrame	ShiftProps \| boolean	{ padding: 10 }	-
allowFlip	FlipProps	-	-
offset	OffsetOptions	-	-
zIndex	number	-	-

If using modal={true} (which is true by default), refer to the PortalProvider installation for more information.

Tooltip.Trigger

Used to trigger opening of the popover when uncontrolled, see YStack in Stacks.

Tooltip.Content

Renders as SizableStack (see Stacks) with an extra size prop that accepts any SizeTokens.

Tooltip.Anchor

Renders as YStack, see Stacks.

When you want the Trigger to be in another location from where the Tooltip attaches, use Anchor. When used, Anchor is where the Tooltip will attach, while Trigger will open it.

This allows you to logically group any tooltips rendered below this component. You can control their delay props, and components inside a TooltipGroup will be smart about opening quicker if you are moving between targets with tooltips, ensuring that subsequent tooltips show immediately rather than after a delay.

See the Floating UI docs for full details on how this works.

Prop	Type	Default	Required
delay	number \| { open?: number; close?: number }	0	-
timeoutMs	number	0	-
preventAnimation	boolean		-

closeOpenTooltips

A small helper function of type () => void that will close any open tooltips.

Scoping

Tooltip supports scoping which lets you mount a single Tooltip instance at the root of your app, while having deeply nested Trigger components anywhere in your tree attach to that single parent Tooltip.

This is useful for performance - you only render Tooltip.Trigger in your list items or buttons, while the heavier Tooltip and Tooltip.Content live at the root. It also lets you style all your tooltips consistently in one place.

When using a global scoped tooltip, you should set zIndex to ensure tooltips appear above dialogs and other portaled content. This is because the global tooltip's portal is mounted outside the stacking context of other portals. Inline tooltips (rendered alongside their trigger) automatically participate in z-index stacking and don't need this.

import { Tooltip } from '@hanzo/gui'

export default ({ children }) => (
  // zIndex needed for global tooltips to appear above dialogs
  <Tooltip scope="tooltip" zIndex={1_000_000}>
    <Tooltip.Content>
      <Tooltip.Arrow />
      {/* your tooltip content renders here */}
    </Tooltip.Content>

    {/* the rest of your app renders inside */}
    {children}
  </Tooltip>
)

export default () => (
  <Tooltip.Trigger scope="tooltip" aria-label="Settings">
    <Button icon={Settings} />
  </Tooltip.Trigger>
)

The scope prop on Trigger connects it to the Tooltip with the matching scope.

On this page