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

# Tooltip

Data Display`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Shows a brief informational popup when hovering or focusing an element.

## When to use

Use Tooltip for short contextual hints on hover or focus. The popup is portaled and inherits the TaoProvider theme.

**Recommended**

- Keep tooltip text short and supplementary.
- Wrap exactly one focusable trigger element.

**Avoid**

- Do not put critical information or interactive content inside a Tooltip.

## Examples


### Basic usage
```tsx preview
import { Button, Tooltip } from '@rockshin/tao-ui';

function TooltipExample() {
  return (
    <Tooltip title="Copy to clipboard">
      <Button variant="secondary">Hover or focus</Button>
    </Tooltip>
  );
}

export default TooltipExample;
```

### Placements
```tsx preview
import { Button, Stack, Tooltip } from '@rockshin/tao-ui';

function TooltipPlacements() {
  return (
    <Stack direction="horizontal" gap="md">
      <Tooltip title="Top" placement="top">
        <Button variant="secondary">Top</Button>
      </Tooltip>
      <Tooltip title="Bottom" placement="bottom">
        <Button variant="secondary">Bottom</Button>
      </Tooltip>
      <Tooltip title="Left" placement="left">
        <Button variant="secondary">Left</Button>
      </Tooltip>
      <Tooltip title="Right" placement="right">
        <Button variant="secondary">Right</Button>
      </Tooltip>
    </Stack>
  );
}

export default TooltipPlacements;
```

### Arrow, color, and controlled visibility
```tsx preview
import { Button, Stack, Tooltip } from '@rockshin/tao-ui';

function TooltipStyles() {
  return (
    <Stack direction="horizontal" gap="md">
      <Tooltip title="No arrow" arrow={false}>
        <Button variant="secondary">No arrow</Button>
      </Tooltip>
      <Tooltip title="Brand color" color="#245b57">
        <Button variant="secondary">Custom color</Button>
      </Tooltip>
      <Tooltip title="Focus also opens this hint">
        <Button variant="secondary">Focus for a hint</Button>
      </Tooltip>
    </Stack>
  );
}

export default TooltipStyles;
```

### Hide the arrow
Set arrow=false to remove the pointer.
```tsx preview
import { Button, Tooltip } from '@rockshin/tao-ui';

export default function TooltipNoArrow() {
  return (
    <Tooltip title="No arrow tooltip" arrow={false}>
      <Button variant="secondary">No arrow</Button>
    </Tooltip>
  );
}
```

### Controlled tooltip
Synchronize visibility through open and onOpenChange.
```tsx preview
import { useState } from 'react';
import { Button, Stack, Tooltip } from '@rockshin/tao-ui';
export default function Example() {
  const [open, setOpen] = useState(false);
  return (
    <Stack direction="horizontal">
      <Button onClick={() => setOpen(!open)}>
        {open ? 'Hide hint' : 'Show hint'}
      </Button>
      <Tooltip open={open} onOpenChange={setOpen} title="Controlled hint">
        <Button>Hint target</Button>
      </Tooltip>
    </Stack>
  );
}
```

### Custom color
color customizes the background; retain readable contrast.
```tsx preview
import { Button, Stack, Tooltip } from '@rockshin/tao-ui';

export default function TooltipCustomColor() {
  return (
    <Stack direction="horizontal" gap="md" align="center">
      <Tooltip title="Brand primary" color="#1677ff">
        <Button variant="secondary">#1677ff</Button>
      </Tooltip>
      <Tooltip title="Warm orange" color="#f76b15">
        <Button variant="secondary">#f76b15</Button>
      </Tooltip>
    </Stack>
  );
}
```

### Hover delays
Delays use seconds; keyboard focus does not wait for a hover delay.
```tsx preview
import { Tooltip, Button } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Tooltip
      title="Wait 0.6 seconds on hover"
      mouseEnterDelay={0.6}
      mouseLeaveDelay={0.2}
    >
      <Button>Hover or focus</Button>
    </Tooltip>
  );
}
```

### Conditional content
An empty title disables the tooltip so hints only appear when useful.
```tsx preview
import { useState } from 'react';
import { Tooltip, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [enabled, setEnabled] = useState(true);
  return (
    <Stack direction="vertical">
      <Button onClick={() => setEnabled(!enabled)}>
        {enabled ? 'Disable hint' : 'Enable hint'}
      </Button>
      <Tooltip title={enabled ? 'Additional information' : null}>
        <Button>Hint target</Button>
      </Tooltip>
    </Stack>
  );
}
```

## API


### [#](#tooltip)Tooltip



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| title | Tooltip content. Empty strings, booleans, null and undefined disable it. | `ReactNode` | `-` |
| placement | Popup side relative to the trigger. Defaults to 'top'. | `TooltipPlacement | undefined` | `-` |
| arrow | Show the arrow pointing at the trigger. Defaults to true. | `boolean | undefined` | `-` |
| mouseEnterDelay | Hover delay in seconds before opening. Defaults to 0.1. Focus opens immediately. | `number | undefined` | `-` |
| mouseLeaveDelay | Delay in seconds before a pointer-leave closes the tooltip. Defaults to
0.1 (antd parity) — re-entering the trigger or content before the
deadline cancels the close. Esc / focus-blur closes stay immediate. | `number | undefined` | `-` |
| color | Custom content background color. | `string | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
| children | Exactly one trigger element. | `ReactNode` **(Required)** | `-` |

