组件 · 浮层
Tooltip
One line that appears on hover or keyboard focus and gives something without a visible label its name, its consequence or its shortcut.
也叫 Hint
import { Tooltip } from "@botiverse/raft-ui";A tooltip is one line that appears on hover or keyboard focus and gives something without a visible label its name, its consequence or its keyboard shortcut. Icon buttons, truncated names, runtime chips and the items of the desktop rail use it.
When to use
| Situation | Use |
|---|---|
| An icon button, a truncated name, a runtime chip ("Runs on Martin's MacBook") | Tooltip |
| An item of the desktop rail | Tooltip on the right, with the destination's name (AppRail) |
| A label that is already visible on the control | Nothing: don't repeat it in a tooltip |
| Content with a link or a button | Popover |
| A person or an agent | PreviewCard |
Anatomy
TooltipProvider: sets the open delay for the tooltips inside it. In raft-ui they open without delay.Tooltip: the root. Required.TooltipTrigger: the element the tooltip describes. Required.TooltipContent: the tooltip, with a small arrow toward the trigger. A leading icon and aKbdfor the shortcut can sit inside it. Required.TooltipPortal: a lower-level part.
The tooltip is layer-hud with foreground-on-hud text, like a toast (Color).
Behavior
- It opens above its trigger, centered on it, and flips below when there is no room above.
side="right"puts it beside the trigger, as on the rail;side="bottom"puts it under the trigger.- It wraps at 20rem, or at the space left in the window.
- It closes when the pointer leaves, when focus leaves and on Esc.
Content
- Write one name or one short sentence, in sentence case: Search, Runs on Martin's MacBook.
- Use the same word in the tooltip as in the trigger's
aria-label. - Put the shortcut in a
Kbdafter the text: Search ⌘K.
Accessibility
- Tooltip wraps the Base UI Tooltip. It provides the
tooltiprole and opens on hover and on keyboard focus. - A tooltip adds to a name; it doesn't replace it. Give every icon-only button its own
aria-label. - Touch screens have no hover. Show the tooltip on press and hold, or write the explanation in the interface instead.
Rules
- Never put a link, a button or anything people must act on in a tooltip: the pointer can't reach it.
API
Tooltip
| Prop | 类型 | 默认值 |
|---|---|---|
| A ref to imperative actions. - `unmount`: Unmounts the tooltip popup. - `close`: Closes the tooltip imperatively when called. | RefObject<TooltipRootActions | null> | |
| The content of the tooltip. This can be a regular React node or a render function that receives the `payload` of the active trigger. | ReactNode | PayloadChildRenderFunction<unknown> | |
| Whether the tooltip is initially open. | boolean | false |
| ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip. | string | |
| Whether the tooltip is disabled. | boolean | false |
| Whether the tooltip contents can be hovered without closing the tooltip. | boolean | false |
| A handle to associate the tooltip with a trigger. If specified, allows external triggers to control the tooltip's open state. Can be created with the Tooltip.createHandle() method. | BaseTooltip.Handle<unknown> | |
| Event handler called when the tooltip is opened or closed. | (open: boolean, eventDetails: BaseTooltip.Root.ChangeEventDetails) => void | |
| Event handler called after any animations complete when the tooltip is opened or closed. | (open: boolean) => void | |
| Whether the tooltip is currently open. | boolean | |
| Determines which axis the tooltip should track the cursor on. | "none" | "both" | "x" | "y" | 'none' |
| ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `open` prop to create a controlled tooltip. There's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set). | string |
TooltipContent
| Prop | 类型 | 默认值 |
|---|---|---|
| HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | ||
| TooltipPortalProps | ||
| How to align the popup relative to the specified side. | Align | "center" |
| Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. | number | OffsetFunction | 0 |
| An element to position the popup against. By default, the popup will be positioned against the trigger. | Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | |
| Minimum distance to maintain between the arrow and the edges of the popup. | number | 5 |
| Determines how to handle collisions when positioning the popup. | CollisionAvoidance | CONTENT_COLLISION_AVOIDANCE |
| An element or a rectangle that delimits the area that the popup is confined to. | Boundary | 'clipping-ancestors' |
| Additional space to maintain from the edge of the collision boundary. | Padding | 5 |
| Whether to disable the popup from tracking any layout shift of its positioning anchor. | boolean | false |
| Determines which CSS `position` property to use. | "fixed" | "absolute" | "fixed" |
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) | |
| Which side of the anchor element to align the popup against. May automatically change to avoid collisions. | Side | "top" |
| Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. | number | OffsetFunction | 0 |
| Whether to maintain the popup in the viewport after the anchor element was scrolled out of view. | boolean | false |
Also takes the attributes of its element.
TooltipPortal
| Prop | 类型 | 默认值 |
|---|---|---|
| A parent element to render the portal element into. | HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | |
| Whether to keep the portal mounted in the DOM while the popup is hidden. | boolean | false |
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) |
Also takes the attributes of its element.
TooltipProvider
| Prop | 类型 | 默认值 |
|---|---|---|
| ReactNode | ||
| How long to wait before closing a tooltip. Specified in milliseconds. | number | |
| How long to wait before opening the tooltip on hover. Specified in milliseconds. | number | 0 |
| Another tooltip will open instantly if the previous tooltip is closed within this timeout. Specified in milliseconds. | number | 400 |
TooltipTrigger
| Prop | 类型 | 默认值 |
|---|---|---|
| How long to wait before closing the tooltip. Specified in milliseconds. | number | 0 |
| Whether the tooltip should close when this trigger is clicked. | boolean | true |
| How long to wait before opening the tooltip on hover. Specified in milliseconds. | number | 600 |
| If `true`, the tooltip will not open when interacting with this trigger. Note that this doesn't apply the `disabled` attribute to the trigger element. If you want to disable the trigger element itself, you can pass the `disabled` prop to the trigger element via the `render` prop. | boolean | false |
| A handle to associate the trigger with a tooltip. | BaseTooltip.Handle<unknown> | |
| A payload to pass to the tooltip when it is opened. | {} | |
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) |
Also takes the attributes of its element.
相关组件
改动
- 0.10.0 · Changed
Tooltip,ComboboxSelectoptions,StepsandTimelineuse the type scale instead of fixed sizes, so they follow the desktop values.