Tooltip 提示

鼠标悬停时展示额外说明文字的气泡提示，支持上下左右四个方向和自定义延迟。

安装

bash

npx polyui add tooltip

需要 TooltipProvider

Tooltip 组件依赖 TooltipProvider 提供的上下文。请在应用根部（如 layout.tsx 或 App.tsx）包裹一次即可，无需为每个 Tooltip 单独添加。

tsx

// layout.tsx (Next.js) or App.tsx
import { TooltipProvider } from "@polyui/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <TooltipProvider>
          {children}
        </TooltipProvider>
      </body>
    </html>
  );
}

默认

tsx

import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@polyui/react/tooltip"
import { Button } from "@polyui/react/button"
export function TooltipDefault() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="sm" />}>Hover me</TooltipTrigger>
        <TooltipContent>
          <p>This is a tooltip</p>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

错误状态

tsx

import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@polyui/react/tooltip"
import { Button } from "@polyui/react/button"
export function TooltipError() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="sm" />}>Error tooltip</TooltipTrigger>
        <TooltipContent className="bg-destructive [&_svg]:bg-destructive [&_svg]:fill-destructive text-white">
          <p>Something went wrong</p>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

带图标

tsx

import { InfoIcon } from "lucide-react"
import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@polyui/react/tooltip"
import { Button } from "@polyui/react/button"
export function TooltipWithIcon() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="sm" />}>With icon</TooltipTrigger>
        <TooltipContent className="max-w-64 text-pretty">
          <div className="flex items-center gap-1.5">
            <InfoIcon className="size-4" />
            <p>Helpful information with an icon</p>
          </div>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

富内容

tsx

import { InfoIcon } from "lucide-react"
import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@polyui/react/tooltip"
import { Button } from "@polyui/react/button"
export function TooltipRichContent() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="sm" />}>Rich content</TooltipTrigger>
        <TooltipContent className="max-w-64 py-3 text-pretty">
          <div className="space-y-1">
            <div className="flex items-center gap-2">
              <InfoIcon className="size-4" />
              <p className="text-sm font-medium">Rich Tooltip Title</p>
            </div>
            <p className="text-background/80">Additional details and context can go here.</p>
          </div>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

方向

tsx

import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@polyui/react/tooltip"
import { Button } from "@polyui/react/button"
export function TooltipDirections() {
  return (
    <TooltipProvider>
      <div className="flex flex-wrap gap-2">
        {(["left", "top", "bottom", "right"] as const).map((side) => (
          <Tooltip key={side}>
            <TooltipTrigger render={<Button variant="outline" size="sm" />}>
              {side.charAt(0).toUpperCase() + side.slice(1)}
            </TooltipTrigger>
            <TooltipContent side={side}>Tooltip on {side}</TooltipContent>
          </Tooltip>
        ))}
      </div>
    </TooltipProvider>
  )
}

圆角

tsx

import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@polyui/react/tooltip"
import { Button } from "@polyui/react/button"
export function TooltipRounded() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="sm" />}>Rounded tooltip</TooltipTrigger>
        <TooltipContent className="rounded-full">
          <p>Rounded tooltip style</p>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

带头像

tsx

import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@polyui/react/tooltip"
import { Button } from "@polyui/react/button"
import { Avatar, AvatarFallback, AvatarImage } from "@polyui/react/avatar"
export function TooltipWithAvatar() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="sm" />}>With avatar</TooltipTrigger>
        <TooltipContent>
          <div className="flex items-center gap-1.5">
            <Avatar className="size-5">
              <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png" alt="User avatar" />
              <AvatarFallback className="text-xs">HR</AvatarFallback>
            </Avatar>
            <p className="font-medium">Hannah Rose</p>
          </div>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

带徽章

tsx

import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@polyui/react/tooltip"
import { Button } from "@polyui/react/button"
import { Badge } from "@polyui/react/badge"
export function TooltipWithBadge() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="sm" />}>With badge</TooltipTrigger>
        <TooltipContent>
          <div className="flex items-center gap-2">
            <p>Status</p>
            <Badge variant="secondary" className="px-1.5 py-px">
              New
            </Badge>
          </div>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

Props — Tooltip

属性	类型	默认值	说明
`delayDuration`	`number`	`700`	鼠标悬停后显示提示的延迟毫秒数。

Props — TooltipContent

属性	类型	默认值	说明
`side`	`"top" \| "right" \| "bottom" \| "left"`	`"top"`	提示气泡相对于触发元素的弹出方向。
`sideOffset`	`number`	`4`	提示气泡与触发元素之间的间距（px）。

Props — TooltipProvider

属性	类型	默认值	说明
`delayDuration`	`number`	`700`	全局默认的悬停延迟毫秒数，可被单个 Tooltip 的 delayDuration 覆盖。
`skipDelayDuration`	`number`	`300`	用户在提示之间快速移动时，跳过延迟的最大时间窗口（ms）。