docs/apps/gui-docs/content/docs/components/tooltip.mdx

---
title: Tooltip
description: A tooltip on web, with only accessibility output on native
name: tooltip
component: Tooltip
package: tooltip
demoName: 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](/ui/z-index) above other content.

<Notice>Note that Tooltip doesn't render on native platforms.</Notice>

## Installation

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

```bash
npm install @hanzogui/tooltip
```

## Anatomy

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

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

## API Reference

### Tooltip

Contains every component for the tooltip.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'groupId',
      type: 'string',
      required: false,
      description: `If given, will work alongside TooltipGroup to ensure only one tooltip in the groups stays open.`,
    },
    {
      name: 'restMs',
      type: 'number',
      required: false,
      description: `Time needed for cursor to rest before showing.`,
    },
    {
      name: 'delay',
      type: `number | { open?: number; close?: number }`,
      required: false,
      description: `Maximum time before showing (can be set independently for open/close).`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down to all sub-components when set for padding, arrow, borderRadius.`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: `The controlled open state of the tooltip.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: `The open state when initially rendered.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
      description: `Event handler called when the open state changes.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      required: false,
      description: `Renders into root of app instead of inline.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      default: '{ padding: 10 }',
      description: `Shifts the tooltip horizontally to stay within viewport bounds. Pass an object to customize shift behavior (mainAxis, crossAxis, padding).`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps',
      required: false,
      description: `See floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
    {
      name: 'zIndex',
      type: 'number',
      required: false,
      description: `Sets the z-index of the tooltip portal. Only needed for global/scoped tooltips mounted at the root - inline tooltips automatically participate in z-index stacking. See the Scoping section below.`,
    },
  ]}
/>

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](#portalprovider) for more information.
</Notice>

### Tooltip.Trigger

Used to trigger opening of the popover when uncontrolled, see YStack in [Stacks](/docs/components/stacks).

### Tooltip.Content

Renders as SizableStack (see [Stacks](/docs/components/stacks)) with an extra `size` prop that accepts any `SizeTokens`.

### Tooltip.Anchor

Renders as YStack, see [Stacks](/docs/components/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.

### TooltipGroup

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](https://floating-ui.com/docs/floatingdelaygroup) for full details on how this works.

<PropsTable
  data={[
    {
      name: 'delay',
      type: 'number | { open?: number; close?: number }',
      default: 0,
      required: false,
      description: `The delay to use for the group.`,
    },
    {
      name: 'timeoutMs',
      type: 'number',
      default: 0,
      required: false,
      description: `An optional timeout to use for the group, which represents when grouping logic will no longer be active after the close delay completes. Useful if you want grouping to last longer than the close delay, for example if there is no close delay at all.`,
    },
    {
      name: 'preventAnimation',
      type: 'boolean',
      default: false,
      required: false,
      description: `Will disable the enter/exit animations while the group is active, but not for the initial enter animation of the first hovered tooltip.`,
    },
  ]}
/>

### 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.

<Notice>
  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.
</Notice>

```tsx fileName=_layout.tsx
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>
)
```

```tsx fileName=MyButton.tsx
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.