> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/tooltip.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Tooltip

Add a brief explanation to a page element.


## Basic usage

Hover or keyboard focus shows the tooltip; Escape closes it. Keep content descriptive; use [Popover](https://ifhover.github.io/leaf-ui/en/components/popover.md) for interactive content.


Save

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tooltip/basic.tsx"
import { Button, Tooltip } from '@ifhover/leaf-ui';

export function TooltipBasic() {
  return (
    <Tooltip content="Save changes to the current project">
      <Button variant="outline">Save</Button>
    </Tooltip>
  );
}
```

Expand code


## Examples

### Placement

Set the preferred position with `placement`; it adjusts when space is limited.


TopSave

BottomSave

LeftSave

RightSave

placements.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tooltip/placements.tsx"
import { Button, Flex, Grid, Text, Tooltip } from '@ifhover/leaf-ui';

const placements = [
  { placement: 'top', label: 'Top' },
  { placement: 'bottom', label: 'Bottom' },
  { placement: 'left', label: 'Left' },
  { placement: 'right', label: 'Right' },
] as const;

export function TooltipPlacements() {
  return (
    <Flex direction="column" gap="md">
      {placements.map(({ placement, label }) => (
        <Grid
          key={placement}
          role="group"
          aria-label={label}
          columns={{ xs: 1, sm: 2 }}
          gap="8px"
          align="center"
        >
          <Text tone="muted">{label}</Text>
          <Tooltip placement={placement} content="Save changes to the current project">
            <Button variant="outline">Save</Button>
          </Tooltip>
        </Grid>
      ))}
    </Flex>
  );
}
```

Expand code

### Disabled tooltip

Tooltip's `disabled` only turns off the tooltip, not the button. A disabled button cannot receive focus; use a focusable wrapper to explain why it is disabled.


Default

Save

Disabled tooltip

Save

disabled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tooltip/disabled.tsx"
import { Button, Flex, Grid, Text, Tooltip } from '@ifhover/leaf-ui';

const states = [
  { disabled: false, label: 'Default' },
  { disabled: true, label: 'Disabled tooltip' },
];

export function TooltipDisabled() {
  return (
    <Flex direction="column" gap="md">
      {states.map(({ disabled, label }) => (
        <Grid
          key={label}
          role="group"
          aria-label={label}
          columns={{ xs: 1, sm: 2 }}
          gap="8px"
          align="center"
        >
          <Text tone="muted">{label}</Text>
          <Flex align="start">
            <Tooltip content="Save changes to the current project" disabled={disabled}>
              <Button variant="outline">Save</Button>
            </Tooltip>
          </Flex>
        </Grid>
      ))}
    </Flex>
  );
}
```

Expand code

### Controlled visibility

Manage visibility with `open` and `onOpenChange`. Without `open`, `defaultOpen` only sets the initial state.


View helpShow tooltipHide tooltip

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tooltip/controlled.tsx"
import { Button, Flex, Tooltip } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function TooltipControlled() {
  const [open, setOpen] = useState(false);
  return (
    <Flex gap="sm" align="center" wrap>
      <Tooltip
        content="This setting applies to the current project"
        open={open}
        onOpenChange={setOpen}
      >
        <Button variant="outline">View help</Button>
      </Tooltip>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Show tooltip
      </Button>
      <Button variant="outline" onClick={() => setOpen(false)}>
        Hide tooltip
      </Button>
    </Flex>
  );
}
```

Expand code


## API

### Tooltip API

Configure hint content, placement and visibility behavior.

The trigger must forward its ref and events. Its existing `aria-describedby` is merged with the tooltip reference. See [PopupOptions](https://ifhover.github.io/leaf-ui/en/api/popup-options.md) for shared popup options.

| Property            | Type                                                                                                                                                                 | Default  | Description                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------- |
| `content`           | `ReactNode`                                                                                                                                                          | Required | Tooltip content; empty strings, null and undefined suppress the tooltip.           |
| `children`          | `ReactElement< HTMLAttributes<HTMLElement> & { ref?: Ref<HTMLElement>; disabled?: boolean } >`                                                                       | Required | Trigger element supporting a ref and events                                        |
| `placement`         | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | `'top'`  | Preferred placement; adjusts when space is limited                                 |
| `arrow`             | `boolean`                                                                                                                                                            | `true`   | Whether to show the arrow pointing to the trigger.                                 |
| `disabled`          | `boolean`                                                                                                                                                            | `false`  | Suppress the tooltip without disabling its trigger.                                |
| `open`              | `boolean`                                                                                                                                                            | —        | Controlled open state.                                                             |
| `defaultOpen`       | `boolean`                                                                                                                                                            | `false`  | Initial open state for uncontrolled usage.                                         |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                            | —        | Open state change                                                                  |
| `enterDelay`        | `number`                                                                                                                                                             | `100`    | Delay in milliseconds before opening on hover.                                     |
| `leaveDelay`        | `number`                                                                                                                                                             | `100`    | Delay in milliseconds before closing after pointer leave.                          |
| `className`         | `string`                                                                                                                                                             | —        | Tooltip panel class                                                                |
| `popupPlacement`    | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | —        | Placement relative to the trigger.                                                 |
| `popupClassName`    | `string`                                                                                                                                                             | —        | Custom class for the popup.                                                        |
| `popupStyle`        | `CSSProperties`                                                                                                                                                      | —        | Custom popup styles.                                                               |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                      | —        | Wrap or extend popup content; retain the supplied content to preserve interaction. |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                  | —        | Return a popup container, including a ShadowRoot.                                  |
