工具提示

用于当用户悬停在元素上时显示附加信息。

import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"

const Demo = () => {
  return (
    <Tooltip content="This is the tooltip content">
      <Button variant="outline" size="sm">
        Hover me
      </Button>
    </Tooltip>
  )
}

设置

为方便使用，为Tooltip 组件创建封闭组件组合。

import { Tooltip as ChakraTooltip, Portal } from "@chakra-ui/react"
import * as React from "react"

export interface TooltipProps extends ChakraTooltip.RootProps {
  showArrow?: boolean
  portalled?: boolean
  portalRef?: React.RefObject<HTMLElement>
  content: React.ReactNode
  contentProps?: ChakraTooltip.ContentProps
  disabled?: boolean
}

export const Tooltip = React.forwardRef<HTMLDivElement, TooltipProps>(
  function Tooltip(props, ref) {
    const {
      showArrow,
      children,
      disabled,
      portalled = true,
      content,
      contentProps,
      portalRef,
      ...rest
    } = props

    if (disabled) return children

    return (
      <ChakraTooltip.Root {...rest}>
        <ChakraTooltip.Trigger asChild>{children}</ChakraTooltip.Trigger>
        <Portal disabled={!portalled} container={portalRef}>
          <ChakraTooltip.Positioner>
            <ChakraTooltip.Content ref={ref} {...contentProps}>
              {showArrow && (
                <ChakraTooltip.Arrow>
                  <ChakraTooltip.ArrowTip />
                </ChakraTooltip.Arrow>
              )}
              {content}
            </ChakraTooltip.Content>
          </ChakraTooltip.Positioner>
        </Portal>
      </ChakraTooltip.Root>
    )
  },
)

另外，您可以使用以下命令将其添加到项目中。

npx @chakra-ui/cli snippet add tooltip

用法

import { Tooltip } from "@/components/ui/tooltip"

<Tooltip content="...">
  <button />
</Tooltip>

示例

箭头

使用 showArrow 属性在工具提示上显示箭头。

import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"

const Demo = () => {
  return (
    <Tooltip showArrow content="This is the tooltip content">
      <Button variant="outline" size="sm">
        Hover me
      </Button>
    </Tooltip>
  )
}

位置

使用 positioning.placement 属性更改工具提示的位置。

import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"

const Demo = () => {
  return (
    <Tooltip
      content="This is the tooltip content"
      positioning={{ placement: "right-end" }}
    >
      <Button variant="outline" size="sm">
        Hover me
      </Button>
    </Tooltip>
  )
}

偏移

使用 positioning.offset 属性更改工具提示的偏移量。

import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"

const Demo = () => {
  return (
    <Tooltip
      content="This is the tooltip content"
      positioning={{ offset: { mainAxis: 4, crossAxis: 4 } }}
    >
      <Button variant="outline" size="sm">
        Hover me
      </Button>
    </Tooltip>
  )
}

延迟

使用 openDelay 和 closeDelay 属性更改工具提示的延迟。

import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"

const Demo = () => {
  return (
    <Tooltip
      content="This is the tooltip content"
      openDelay={500}
      closeDelay={100}
    >
      <Button variant="outline" size="sm">
        Delay (open: 500ms, close: 100ms)
      </Button>
    </Tooltip>
  )
}

自定义背景

使用 --tooltip-bg CSS 变量更改工具提示的背景颜色。

import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { FaBell } from "react-icons/fa"

export const TooltipWithCustomBg = () => (
  <Tooltip
    showArrow
    content="This is the tooltip content"
    contentProps={{ css: { "--tooltip-bg": "tomato" } }}
  >
    <Button variant="outline" size="sm">
      <FaBell /> 3
    </Button>
  </Tooltip>
)

受控

使用 open 和 onOpenChange 属性控制工具提示的可见性。

"use client"

import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { useState } from "react"

const Demo = () => {
  const [open, setOpen] = useState(false)
  return (
    <Tooltip
      content="Tooltip Content"
      open={open}
      onOpenChange={(e) => setOpen(e.open)}
    >
      <Button size="sm">{open ? "Hide" : "Show"} tooltip</Button>
    </Tooltip>
  )
}

存储

控制工具提示的另一种方法是使用 RootProvider 组件和 useTooltip 存储钩子。

这样，您可以从工具提示外部访问工具提示状态和方法。

"use client"

import { Button, HStack, Tooltip, useTooltip } from "@chakra-ui/react"

const Demo = () => {
  const tooltip = useTooltip()
  const toggleOpen = () => tooltip.setOpen(!tooltip.open)
  return (
    <HStack>
      <Button size="sm" variant="subtle" onClick={toggleOpen}>
        Toggle
      </Button>
      <Tooltip.RootProvider value={tooltip}>
        <Tooltip.Trigger asChild>
          <Button variant="outline">Tooltip Target</Button>
        </Tooltip.Trigger>
        <Tooltip.Positioner>
          <Tooltip.Content>This is the tooltip content</Tooltip.Content>
        </Tooltip.Positioner>
      </Tooltip.RootProvider>
    </HStack>
  )
}

交互式

使用 interactive 属性在与工具提示内容交互时保持其打开状态。

import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"

const Demo = () => {
  return (
    <Tooltip content="This is the tooltip content" interactive>
      <Button variant="outline" size="sm">
        Hover me
      </Button>
    </Tooltip>
  )
}

禁用

使用 disabled 属性禁用工具提示。禁用时，工具提示将不会显示。

import { Button } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"

const Demo = () => {
  return (
    <Tooltip content="This is the tooltip content" disabled>
      <Button variant="outline" size="sm">
        Hover me
      </Button>
    </Tooltip>
  )
}

带头像

这是一个如何将 Tooltip 组件与 Avatar 组件一起使用的示例。

import { Avatar } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { useId } from "react"

const Demo = () => {
  const id = useId()
  return (
    <Tooltip ids={{ trigger: id }} content="Segun Adebayo is online">
      <Avatar.Root ids={{ root: id }}>
        <Avatar.Image src="https://bit.ly/sage-adebayo" />
        <Avatar.Fallback name="Segun Adebayo" />
      </Avatar.Root>
    </Tooltip>
  )
}

带复选框

这是一个如何将 Tooltip 组件与 Checkbox 组件一起使用的示例。

欢迎

import { Checkbox } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { useId } from "react"

const Demo = () => {
  const id = useId()
  return (
    <Tooltip ids={{ trigger: id }} content="This is the tooltip content">
      <Checkbox.Root ids={{ root: id }}>
        <Checkbox.HiddenInput />
        <Checkbox.Control />
        <Checkbox.Label>Welcome</Checkbox.Label>
      </Checkbox.Root>
    </Tooltip>
  )
}

带菜单项

这是一个如何将 Tooltip 与 MenuItem 组件一起使用的示例。

import { Button, Menu, Portal, Show } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"

const Demo = () => {
  return (
    <Menu.Root>
      <Menu.Trigger asChild>
        <Button variant="outline" size="sm">
          Open
        </Button>
      </Menu.Trigger>
      <Portal>
        <Menu.Positioner>
          <Menu.Content>
            <MenuItem value="new-txt" title="This is the tooltip content">
              Open tooltip
            </MenuItem>
            <MenuItem value="new-file">New File...</MenuItem>
            <MenuItem value="new-win">New Window</MenuItem>
            <MenuItem value="export">Export</MenuItem>
          </Menu.Content>
        </Menu.Positioner>
      </Portal>
    </Menu.Root>
  )
}

const MenuItem = (props: Menu.ItemProps) => {
  const { value, title, ...rest } = props
  return (
    <Show when={title} fallback={<Menu.Item value={value} {...rest} />}>
      <Tooltip
        ids={{ trigger: value }}
        openDelay={200}
        closeDelay={0}
        positioning={{ placement: "right" }}
        content={title}
      >
        <Menu.Item value={value} {...rest} />
      </Tooltip>
    </Show>
  )
}

带菜单触发器

这是一个如何将 Tooltip 与 MenuTrigger 组件一起使用的示例。

"use client"

import { Button, Menu, Portal } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { useId } from "react"

const Demo = () => {
  const triggerId = useId()
  return (
    <Menu.Root ids={{ trigger: triggerId }}>
      <Tooltip
        ids={{ trigger: triggerId }}
        positioning={{ placement: "top" }}
        content="Tooltip content"
      >
        <Menu.Trigger asChild>
          <Button variant="outline" size="sm">
            Open
          </Button>
        </Menu.Trigger>
      </Tooltip>
      <Portal>
        <Menu.Positioner>
          <Menu.Content>
            <Menu.Item value="new-txt">Open tooltip</Menu.Item>
            <Menu.Item value="new-file">New File...</Menu.Item>
            <Menu.Item value="new-win">New Window</Menu.Item>
            <Menu.Item value="export">Export</Menu.Item>
          </Menu.Content>
        </Menu.Positioner>
      </Portal>
    </Menu.Root>
  )
}

带开关

这是一个如何将 Tooltip 包装在 Switch 组件周围的示例。

切换

import { Switch } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { useId } from "react"

const Demo = () => {
  const id = useId()
  return (
    <Tooltip ids={{ trigger: id }} content="This is the tooltip content">
      <Switch.Root ids={{ root: id }}>
        <Switch.HiddenInput />
        <Switch.Control />
        <Switch.Label>Toggle</Switch.Label>
      </Switch.Root>
    </Tooltip>
  )
}

带选项卡

这是一个如何将 Tooltip 包装在 Tabs 组件周围的示例。

管理您的团队成员

import { Tabs } from "@chakra-ui/react"
import { Tooltip } from "@/components/ui/tooltip"
import { LuFolder, LuSquareCheck, LuUser } from "react-icons/lu"

const Demo = () => {
  return (
    <Tabs.Root defaultValue="members">
      <Tabs.List>
        <Tooltip
          positioning={{ placement: "top" }}
          ids={{ trigger: "members" }}
          content="This is the tooltip content"
        >
          {/* TODO: Remove this once Zag.js is fixed */}
          <span>
            <Tabs.Trigger value="members">
              <LuUser />
              Members
            </Tabs.Trigger>
          </span>
        </Tooltip>
        <Tabs.Trigger value="projects">
          <LuFolder />
          Projects
        </Tabs.Trigger>
        <Tabs.Trigger value="tasks">
          <LuSquareCheck />
          Settings
        </Tabs.Trigger>
      </Tabs.List>
      <Tabs.Content value="members">Manage your team members</Tabs.Content>
      <Tabs.Content value="projects">Manage your projects</Tabs.Content>
      <Tabs.Content value="tasks">
        Manage your tasks for freelancers
      </Tabs.Content>
    </Tabs.Root>
  )
}

属性

根

属性	默认	类型
`closeDelay`	`'500'`	`数字` 工具提示的关闭延迟。
`closeOnClick`	`true`	`布尔值` 点击时工具提示是否应该关闭
`closeOnEscape`	`true`	`布尔值` 当按下 Esc 键时是否关闭工具提示。
`closeOnPointerDown`	`true`	`布尔值` 在指针按下时是否关闭工具提示。
`closeOnScroll`	`true`	`布尔值` 滚动时工具提示是否应该关闭
`interactive`	`false`	`布尔值` 工具提示内容是否可交互。在此模式下，当用户悬停在内容上时，工具提示将保持打开状态。
`lazyMount`	`true`	`布尔值` 是否启用惰性挂载
`openDelay`	`'1000'`	`数字` 工具提示的打开延迟。
`unmountOnExit`	`true`	`布尔值` 是否在退出时卸载。
`aria-label`		`字符串` 工具提示的自定义标签。
`defaultOpen`		`布尔值` 工具提示首次渲染时的初始打开状态。当您不需要控制其打开状态时使用。
`disabled`		`布尔值` 工具提示是否禁用
`id`		`字符串` 工具提示的 `id`。
`ids`		`Partial<{ trigger: string content: string arrow: string positioner: string }>` 工具提示中元素的 id。对组合有用。
`immediate`		`布尔值` 是否立即同步当前更改或将其推迟到下一帧
`onExitComplete`		`() => void` 在关闭状态下动画结束时调用的函数
`onOpenChange`		`(details: OpenChangeDetails) => void` 工具提示打开时调用的函数。
`open`		`布尔值` 工具提示是否打开
`positioning`		`PositioningOptions` 用户提供的用于定位弹出内容体的选项
`present`		`布尔值` 节点是否存在（由用户控制）

切换提示

仅客户端

工具提示

.css-vfo6uh{color:var(--chakra-colors-fg);-webkit-text-decoration:underline;text-decoration:underline;text-underline-offset:3px;text-decoration-thickness:2px;text-decoration-color:var(--chakra-colors-border-emphasized);font-weight:500;}设置

设置