import { Tooltip, TooltipProvider, Button } from "@cloudflare/kumo";
import { PlusIcon } from "@phosphor-icons/react";

export function TooltipHeroDemo() {
  return (
    <TooltipProvider>
      <Tooltip
        content="Add new item"
        render={
          <Button shape="square" icon={PlusIcon} aria-label="Add new item" />
        }
      />
    </TooltipProvider>
  );
}

安装

桶式导出

import { Tooltip, TooltipProvider } from "@cloudflare/kumo";

细粒度导入

import { Tooltip, TooltipProvider } from "@cloudflare/kumo/components/tooltip";

用法

import { Tooltip, Button } from "@cloudflare/kumo";

export default function Example() {
  return (
    <Tooltip content="Tooltip text" render={<Button />}>
      Hover me
    </Tooltip>
  );
}

如需在多个 tooltip 之间统一延迟分组,请参阅 TooltipProvider

示例

基础 Tooltip

import { Tooltip, TooltipProvider, Button } from "@cloudflare/kumo";
import { PlusIcon } from "@phosphor-icons/react";

export function TooltipBasicDemo() {
  return (
    <TooltipProvider>
      <Tooltip
        content="Add"
        render={<Button shape="square" icon={PlusIcon} aria-label="Add" />}
      />
    </TooltipProvider>
  );
}

多个 Tooltip

import { Tooltip, TooltipProvider, Button } from "@cloudflare/kumo";
import { PlusIcon, TranslateIcon } from "@phosphor-icons/react";

export function TooltipMultipleDemo() {
  return (
    <TooltipProvider>
      <div className="flex gap-2">
        <Tooltip
          content="Add"
          render={<Button shape="square" icon={PlusIcon} aria-label="Add" />}
        />
        <Tooltip
          content="Change language"
          render={
            <Button
              shape="square"
              icon={TranslateIcon}
              aria-label="Change language"
            />
          }
        />
      </div>
    </TooltipProvider>
  );
}

长内容 / 溢出

长内容的 Tooltip 会自动使用 Base UI Positioner 提供的 --available-width, 将宽度限制在可用视口范围之内。悬停到边缘按钮上,即可看到 tooltip 换行而不是溢出视口。

import { Tooltip, TooltipProvider, Button } from "@cloudflare/kumo";

/**
 * Control the delay before opening and closing the tooltip.
 * `delay` controls open delay (default: 600ms), `closeDelay` controls close delay (default: 0ms).
 */
/**
 * Demonstrates that long tooltip content respects available viewport space.
 * Tooltips near the edge of the viewport constrain their width to
 * `--available-width` so they don't overflow.
 */
export function TooltipOverflowDemo() {
  const longContent =
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco.";
  return (
    <TooltipProvider>
      <div className="flex w-full justify-between">
        <Tooltip
          content={longContent}
          side="bottom"
          render={<Button variant="secondary" />}
        >
          Near left edge
        </Tooltip>
        <Tooltip
          content={longContent}
          side="bottom"
          render={<Button variant="secondary" />}
        >
          Centered
        </Tooltip>
        <Tooltip
          content={longContent}
          side="bottom"
          render={<Button variant="secondary" />}
        >
          Near right edge
        </Tooltip>
      </div>
    </TooltipProvider>
  );
}

延迟控制

使用 delay 控制打开前的等待时长(默认 600ms),使用 closeDelay 控制 关闭前的等待时长(默认 0ms)。

import { Tooltip, TooltipProvider, Button } from "@cloudflare/kumo";

export function TooltipDelayDemo() {
  return (
    <TooltipProvider>
      <div className="flex gap-4">
        <Tooltip
          content="Opens after 1 second"
          delay={1000}
          render={<Button variant="secondary" />}
        >
          1s open delay
        </Tooltip>
        <Tooltip
          content="Stays open 500ms after leaving"
          closeDelay={500}
          render={<Button variant="secondary" />}
        >
          500ms close delay
        </Tooltip>
        <Tooltip
          content="Instant open, stays 1s"
          delay={0}
          closeDelay={1000}
          render={<Button variant="secondary" />}
        >
          Instant + 1s close
        </Tooltip>
      </div>
    </TooltipProvider>
  );
}

TooltipProvider

TooltipProvider 将多个 tooltip 分组,使第一个 tooltip 显示后,切换到 其他 tooltip 时会跳过打开延迟。将它放在应用根节点或布局中一次即可; 不要在每个 Tooltip 外面分别包裹。

// Wrap your app or layout once
<TooltipProvider>
  <App />
</TooltipProvider>

// Then use Tooltip anywhere inside
<Tooltip content="Add" render={<Button shape="square" icon={PlusIcon} />} />

API 参考

Tooltip

PropTypeDefaultDescription
side"top" | "bottom" | "left" | "right""top"-
classNamestring-Additional CSS classes
childrenReactNode-Child elements
content*ReactNode-Content to display in the tooltip

TooltipProvider

PropTypeDefaultDescription
delaynumber600How long to wait (ms) before opening a tooltip once the pointer enters the trigger.
closeDelaynumber0How long to wait (ms) before closing a tooltip.
timeoutnumber400Grace period (ms) during which a just-closed tooltip's delay is skipped when another tooltip opens.