Tooltip
A short label shown on hover and keyboard focus, for an icon button or a truncated text.
A tooltip shows a few words next to an element while the pointer rests on it or it has keyboard focus: the name of an icon button, the full text of a truncated label. It holds no interactive content and nothing the reader cannot do without; on a touch screen it is never seen. For content the reader works with, use a popover.
Hover or focus a button.
// apps/docs/examples/ui/tooltip.tsx'use client';
import {useState} from 'react';import {CopyIcon, DownloadIcon, PrinterIcon} from 'lucide-react';
import {Button} from '@workspace/active-ui/components/primitives/button';import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger,} from '@workspace/active-ui/components/primitives/tooltip';
const ACTIONS = [ {label: 'Copy the statement', icon: CopyIcon}, {label: 'Download as PDF', icon: DownloadIcon}, {label: 'Print', icon: PrinterIcon},];
/** * A short label for an icon button, shown on pointer hover and on keyboard * focus. The tooltip repeats the button's accessible name for sighted * readers; it is not the name. One `TooltipProvider` makes the next tooltip * open at once while the pointer moves along a row of buttons. */export default function TooltipExample() { const [last, setLast] = useState<string | null>(null); return ( <div className="flex flex-col items-center gap-3"> <TooltipProvider> <div className="flex gap-1" role="group" aria-label="Statement"> {ACTIONS.map(({label, icon: Icon}) => ( <Tooltip key={label}> <TooltipTrigger render={ <Button variant="ghost" size="icon" aria-label={label} onClick={() => setLast(label)} /> } > <Icon aria-hidden /> </TooltipTrigger> <TooltipContent side="bottom">{label}</TooltipContent> </Tooltip> ))} </div> </TooltipProvider> <p className="text-muted-foreground text-sm" aria-live="polite"> {last ? `Chosen: ${last}` : 'Hover or focus a button.'} </p> </div> );}Usage#
import { Tooltip, TooltipContent, TooltipTrigger,} from '@workspace/active-ui/components/primitives/tooltip';
<Tooltip> <TooltipTrigger render={<Button variant="ghost" size="icon" aria-label="Print" />} > <PrinterIcon aria-hidden /> </TooltipTrigger> <TooltipContent>Print</TooltipContent></Tooltip>;Delays and the provider#
A tooltip opens after the pointer has rested on the trigger for
delay(default600ms, onTooltip) and closes afterTrigger close(defaultDelay 0).Tooltipgroups tooltips. In this package itsProvider delayis0: every tooltip inside it opens at once. Put one provider around a row of icon buttons, or around the application, when readers move from one button to the next; leave it out where an immediate tooltip would get in the way.Tooltipis placed byContent side(defaulttop) andalign, with an arrow.
What your application provides#
The accessible name of the trigger, as
aria-or visible text. The tooltip is not the name: it repeats it for sighted readers.label The tooltip text, in your reader's language.
Accessibility and keyboard#
Keyboard focus on the trigger opens the tooltip as hover does;
Escapecloses it.The trigger stays an ordinary button or link: the tooltip adds no tab stop.
API#
TooltipContent#
Import from @workspace/
All props come from the Base UI part this component is built on.
Props
- Type
Align- Default
'center'
How to align the popup relative to the specified side.
- Type
number | OffsetFunction - Default
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:
data.: the dimensions of the anchor element with propertiesanchor widthandheight.data.: the dimensions of the positioner element with propertiespositioner widthandheight.data.: which side of the anchor element the positioner is aligned against.side data.: how the positioner is aligned relative to the specified side.align
- Type
Side- Default
'top'
Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
- Type
number | OffsetFunction - Default
0
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:
data.: the dimensions of the anchor element with propertiesanchor widthandheight.data.: the dimensions of the positioner element with propertiespositioner widthandheight.data.: which side of the anchor element the positioner is aligned against.side data.: how the positioner is aligned relative to the specified side.align
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
TooltipProvider#
Import from @workspace/
All props come from the Base UI part this component is built on.
Props
- Type
ReactNode
The content of this part, in the forms its type allows.
- Type
number
How long to wait before closing a tooltip. Specified in milliseconds.
- Type
number- Default
0
How long to wait before opening the tooltip on hover. Specified in milliseconds.
- Type
number- Default
400
Another tooltip will open instantly if the previous tooltip is closed within this timeout. Specified in milliseconds.
Takes only the props listed.
Other parts#
Tooltip
All props come from the Base UI part this component is built on.
Props
- Type
boolean
Whether the tooltip is currently open.
- Type
boolean- Default
false
Whether the tooltip is initially open.
To render a controlled tooltip, use the open prop instead.
- Type
PayloadChild Render Function<…> 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.
- Type
string | null
ID of the trigger that the tooltip is associated with. This is useful in conjunction with the default prop to create an initially open tooltip.
- Type
boolean- Default
false
Whether the tooltip is disabled.
- Type
boolean- Default
false
Whether the tooltip contents can be hovered without closing the tooltip.
- Type
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.
- Type
"both""none""x""y"- Default
'none'
Determines which axis the tooltip should track the cursor on.
- Type
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).
- Type
RefObject<…>
A ref to imperative actions.
unmount: Ends the closing phase of the tooltip after an externally controlled closing animation finishes. CallpreventinUnmount On Close() onfirst, otherwise the tooltip completes closing on its own. Whether it leaves the DOM is decided byOpen Change keepon the portal.Mounted close: Closes the tooltip imperatively when called.
Events
Called by the component when something happens.
- Type
(open, eventDetails) => void
Event handler called when the tooltip is opened or closed.
- Type
(open: boolean) => void
Event handler called after any animations complete when the tooltip is opened or closed.
Takes only the props listed.
TooltipTrigger
All props come from the Base UI part this component is built on.
Props
- Type
number- Default
0
How long to wait before closing the tooltip. Specified in milliseconds.
- Type
boolean- Default
true
Whether the tooltip should close when this trigger is clicked.
- Type
number- Default
600
How long to wait before opening the tooltip on hover. Specified in milliseconds.
- Type
boolean- Default
false
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.
- Type
TooltipHandle<unknown>
A handle to associate the trigger with a tooltip.
- Type
unknown
A payload to pass to the tooltip when it is opened.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
This page adapts the Tooltip documentation of shadcn/ui (MIT licence) to this package; see Third-party notices.