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

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

# Tooltip 文字提示

为页面元素补充简短说明。


## 基础用法

悬停或键盘聚焦可展示提示，Escape 关闭。提示只放简短说明；需要交互内容时使用 [Popover](https://ifhover.github.io/leaf-ui/components/popover.md)。


保存

basic.tsx

复制代码

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

export function TooltipBasic() {
  return (
    <Tooltip content="保存当前项目的修改">
      <Button variant="outline">保存</Button>
    </Tooltip>
  );
}
```

展开代码


## 示例

### 提示位置

通过 `placement` 设置期望位置，空间不足时会自动调整。


上方保存

下方保存

左侧保存

右侧保存

placements.tsx

复制代码

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

const placements = [
  { placement: 'top', label: '上方' },
  { placement: 'bottom', label: '下方' },
  { placement: 'left', label: '左侧' },
  { placement: 'right', label: '右侧' },
] 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="保存当前项目的修改">
            <Button variant="outline">保存</Button>
          </Tooltip>
        </Grid>
      ))}
    </Flex>
  );
}
```

展开代码

### 禁用提示

Tooltip 的 `disabled` 只关闭提示，不会禁用按钮。禁用按钮本身不能接收焦点；如需解释原因，可使用外层可聚焦的元素作为提示触发器。


默认

保存

禁用提示

保存

disabled.tsx

复制代码

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

const states = [
  { disabled: false, label: '默认' },
  { disabled: true, label: '禁用提示' },
];

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="保存当前项目的修改" disabled={disabled}>
              <Button variant="outline">保存</Button>
            </Tooltip>
          </Flex>
        </Grid>
      ))}
    </Flex>
  );
}
```

展开代码

### 受控展开

使用 `open` 与 `onOpenChange` 管理显示状态。不传 `open` 时，`defaultOpen` 只设置初始状态。


查看说明展开提示收起提示

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/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="该设置应用于当前项目" open={open} onOpenChange={setOpen}>
        <Button variant="outline">查看说明</Button>
      </Tooltip>
      <Button variant="outline" onClick={() => setOpen(true)}>
        展开提示
      </Button>
      <Button variant="outline" onClick={() => setOpen(false)}>
        收起提示
      </Button>
    </Flex>
  );
}
```

展开代码


## API

### Tooltip API

配置提示内容、出现位置和展开方式。

触发元素需透传 ref 与事件；现有的 `aria-describedby` 会与提示关联合并。共享浮层参数见 [PopupOptions](https://ifhover.github.io/leaf-ui/api/popup-options.md)。

| 属性                  | 类型                                                                                                                                                                   | 默认值     | 说明                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------- |
| `content`           | `ReactNode`                                                                                                                                                          | 必填      | 提示内容；为空字符串、null 或 undefined 时不显示。 |
| `children`          | `ReactElement< HTMLAttributes<HTMLElement> & { ref?: Ref<HTMLElement>; disabled?: boolean } >`                                                                       | 必填      | 触发元素，需支持 ref 和事件                  |
| `placement`         | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | `'top'` | 期望展示位置，空间不足时自动调整                  |
| `arrow`             | `boolean`                                                                                                                                                            | `true`  | 是否显示指向触发元素的箭头。                    |
| `disabled`          | `boolean`                                                                                                                                                            | `false` | 禁止显示提示，不禁用触发元素。                   |
| `open`              | `boolean`                                                                                                                                                            | —       | 受控的展开状态。                          |
| `defaultOpen`       | `boolean`                                                                                                                                                            | `false` | 非受控模式的初始展开状态。                     |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                            | —       | 展开状态变化                            |
| `enterDelay`        | `number`                                                                                                                                                             | `100`   | 悬停后等待多少毫秒再打开。                     |
| `leaveDelay`        | `number`                                                                                                                                                             | `100`   | 指针离开后等待多少毫秒再关闭。                   |
| `className`         | `string`                                                                                                                                                             | —       | 提示浮层类名                            |
| `popupPlacement`    | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | —       | 浮层相对触发控件的位置。                      |
| `popupClassName`    | `string`                                                                                                                                                             | —       | 浮层的自定义类名。                         |
| `popupStyle`        | `CSSProperties`                                                                                                                                                      | —       | 浮层的自定义样式。                         |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                      | —       | 包装或补充面板内容，保留传入的内容以维持交互。           |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                  | —       | 返回浮层的挂载容器，也可返回 ShadowRoot。        |
