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

# Tooltip

数据展示`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

在悬停或键盘聚焦时展示简短补充说明。

## 何时使用

图标、缩写或控件需要一行辅助解释时使用 Tooltip。

**推荐**

- 内容保持简短。
- 确保键盘聚焦也能触发。

**避免**

- 关键说明或交互内容不要只放在 Tooltip 中。

## 代码演示


### 基础用法
```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;
```

### 弹出位置
```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;
```

### 箭头、颜色与受控显示
```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;
```

### 不显示箭头
arrow=false 去掉指向箭头。
```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>
  );
}
```

### 受控提示
用 open 与 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>
  );
}
```

### 自定义颜色
color 自定义提示背景，使用时保证文字对比度。
```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>
  );
}
```

### 悬停延迟
延迟以秒为单位，键盘焦点不等待悬停延迟。
```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>
  );
}
```

### 条件提示
title 为空时禁用提示，适合仅在需要解释时显示。
```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



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| 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 | 节点类名 | `string | undefined` | `-` |
| style | 节点样式 | `CSSProperties | undefined` | `-` |
| children | Exactly one trigger element. | `ReactNode` **(必填)** | `-` |

