Tooltip · ui.voila.dev

Usage

import { Tooltip } from "@voila.dev/ui/tooltip";

<Tooltip.Root>
	<Tooltip.Trigger render={<Button size="icon" aria-label="Save" />}>
		<FloppyDiskIcon />
	</Tooltip.Trigger>
	<Tooltip.Content>Save report</Tooltip.Content>
</Tooltip.Root>

One line naming a control, on hover or focus. It is the smallest overlay here and the most misused: a tooltip cannot hold a link, a button, or anything a person must interact with, because it disappears when the pointer leaves and never appears on touch at all. If the content matters, it belongs on the page or in a Popover. An icon button's tooltip is a convenience — its aria-label is what actually names it.

Recipes

Wrap the app once in Tooltip.Provider so tooltips share a delay: the first one waits, the rest open immediately while the pointer keeps moving along a toolbar. Without it every tooltip re-waits and a row of icon buttons feels broken.

Positioning follows the same side/align/sideOffset model as Popover.

API

Tooltip.Root

Prop	Type	Default
`actionsRef`	`RefObject<TooltipRootActions \| null>`	—	A ref to imperative actions.
`children`	`PayloadChildRenderFunction<unknown> \| ReactNode`	—	The content of the tooltip. This can be a regular React node or a render function that receives the `payload` of the active trigger.
`defaultOpen`	`boolean`	—	Whether the tooltip is initially open. To render a controlled tooltip, use the `open` prop instead.
`defaultTriggerId`	`string \| null`	—	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.
`delay`	`number`	—	How long to wait before opening a tooltip. Specified in milliseconds.
`disabled`	`boolean`	—	Whether the tooltip is disabled.
`disableHoverablePopup`	`boolean`	—	Whether the tooltip contents can be hovered without closing the tooltip.
`handle`	`TooltipHandle<unknown>`	—	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.
`onOpenChange`	`((open: boolean, eventDetails: TooltipRootChangeEventDetails) => void)`	—	Event handler called when the tooltip is opened or closed.
`onOpenChangeComplete`	`((open: boolean) => void)`	—	Event handler called after any animations complete when the tooltip is opened or closed.
`open`	`boolean`	—	Whether the tooltip is currently open.
`trackCursorAxis`	`"both" \| "none" \| "x" \| "y"`	—	Determines which axis the tooltip should track the cursor on.
`triggerId`	`string \| null`	—	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).

Plus the DOM props of the element it renders. Source: tooltip/components/tooltip-root.tsx.

Tooltip.Content

Prop	Type	Default
`align`	`Align`	`"center"`	How to align the popup relative to the specified side.
`alignOffset`	`number \| OffsetFunction`	`0`	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. The function takes a `data` object parameter with the following properties:
`className`	`string` \| `((state: TooltipPopupState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`collisionPadding`	`Padding`	—	Additional space to maintain from the edge of the collision boundary.
`render`	`ComponentRenderFn<HTMLProps, TooltipPopupState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`side`	`Side`	`"top"`	Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
`sideOffset`	`number \| OffsetFunction`	`4`	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. The function takes a `data` object parameter with the following properties:
`style`	`CSSProperties` \| `((state: TooltipPopupState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: tooltip/components/tooltip-content.tsx.

Tooltip.Provider

Prop	Type	Default
`children`	`ReactNode`	—
`closeDelay`	`number`	—	How long to wait before closing a tooltip. Specified in milliseconds.
`delay`	`number`	`0`	How long to wait before opening a tooltip. Specified in milliseconds.
`timeout`	`number`	—	Another tooltip will open instantly if the previous tooltip is closed within this timeout. Specified in milliseconds.

Plus the DOM props of the element it renders. Source: tooltip/components/tooltip-provider.tsx.

Tooltip.Trigger

Prop	Type	Default
`className`	`string` \| `((state: TooltipTriggerState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`closeDelay`	`number`	—	How long to wait before closing the tooltip. Specified in milliseconds.
`closeOnClick`	`boolean`	—	Whether the tooltip should close when this trigger is clicked.
`delay`	`number`	—	How long to wait before opening the tooltip. Specified in milliseconds.
`disabled`	`boolean`	—	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.
`handle`	`TooltipHandle<unknown>`	—	A handle to associate the trigger with a tooltip.
`payload`	`unknown`	—	A payload to pass to the tooltip when it is opened.
`render`	`ComponentRenderFn<HTMLProps, TooltipTriggerState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: TooltipTriggerState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: tooltip/components/tooltip-trigger.tsx.

Popover · HoverCard · Kbd · Button