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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/tooltip.md.

Tooltip 文字提示

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

基础用法

悬停或键盘聚焦可展示提示,Escape 关闭。提示只放简短说明;需要交互内容时使用 Popover。

basic.tsx
import { Button, Tooltip } from '@ifhover/leaf-ui';

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

示例

提示位置

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

上方
下方
左侧
右侧
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
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
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。

属性类型默认值说明
contentReactNode必填提示内容;为空字符串、null 或 undefined 时不显示。
childrenReactElement< 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'期望展示位置,空间不足时自动调整
arrowbooleantrue是否显示指向触发元素的箭头。
disabledbooleanfalse禁止显示提示,不禁用触发元素。
openboolean—受控的展开状态。
defaultOpenbooleanfalse非受控模式的初始展开状态。
onOpenChange(open: boolean) => void—展开状态变化
enterDelaynumber100悬停后等待多少毫秒再打开。
leaveDelaynumber100指针离开后等待多少毫秒再关闭。
classNamestring—提示浮层类名
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—浮层相对触发控件的位置。
popupClassNamestring—浮层的自定义类名。
popupStyleCSSProperties—浮层的自定义样式。
popupRender(content: React.ReactNode) => React.ReactNode—包装或补充面板内容,保留传入的内容以维持交互。
getPopupContainer() => Element | DocumentFragment—返回浮层的挂载容器,也可返回 ShadowRoot。