Components
Tooltip
Short hints shown on hover or keyboard focus.
Tooltip explains an element with a short piece of text. Use it for icon buttons, shortcut hints,
and brief clarification. Do not put buttons, links, forms, or other interactive content inside a
tooltip; use Popover instead.
The component is built on Base UI Tooltip. Import it from @orkest/ui/client.
Basic usage#
Wrap tooltips in TooltipProvider to share the hover delay. The provider defaults to a 500ms open
delay and no close delay.
import { IconButton, Stack } from '@orkest/ui';
import {
Tooltip,
TooltipArrow,
TooltipContent,
TooltipPortal,
TooltipProvider,
TooltipTrigger,
} from '@orkest/ui/client';
import { Copy, Settings, SlidersHorizontal } from 'lucide-react';
export function Example() {
return (
<TooltipProvider delay={300}>
<Stack direction="row" gap={3} align="center">
<Tooltip>
<TooltipTrigger
render={<IconButton icon={Settings} label="Settings" variant="outline" />}
/>
<TooltipPortal>
<TooltipContent>
Manage workspace settings
<TooltipArrow />
</TooltipContent>
</TooltipPortal>
</Tooltip>
<Tooltip>
<TooltipTrigger
render={<IconButton icon={SlidersHorizontal} label="Filters" variant="outline" />}
/>
<TooltipPortal>
<TooltipContent>Filter the current results</TooltipContent>
</TooltipPortal>
</Tooltip>
<Tooltip>
<TooltipTrigger
render={<IconButton icon={Copy} label="Copy link" variant="outline" />}
/>
<TooltipPortal>
<TooltipContent>Copy link ⌘C</TooltipContent>
</TooltipPortal>
</Tooltip>
</Stack>
</TooltipProvider>
);
}Anatomy#
TooltipProviderconfigures the shared delay and close delay.Tooltipowns the open state.TooltipTriggershows the tooltip on hover and keyboard focus.TooltipPortalmoves the tooltip to the document body.TooltipContentrenders the short hint.TooltipArrowadds an optional arrow.
Text triggers and shortcuts#
TooltipContent accepts short text and inline shortcut hints. Avoid block-level interactive
components.
import {
Tooltip,
TooltipContent,
TooltipPortal,
TooltipProvider,
TooltipTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<TooltipProvider delay={200}>
<Tooltip>
<TooltipTrigger variant="link">What is a workspace?</TooltipTrigger>
<TooltipPortal>
<TooltipContent maxWidth="14rem">
A workspace groups projects, members, and billing in one place.
</TooltipContent>
</TooltipPortal>
</Tooltip>
</TooltipProvider>
);
}Positioning and arrow#
TooltipContent defaults to side="top", align="center", and sideOffset={6}. It flips
automatically when the tooltip would overflow the viewport.
import {
Tooltip,
TooltipArrow,
TooltipContent,
TooltipPortal,
TooltipProvider,
TooltipTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<TooltipProvider delay={0}>
<Tooltip>
<TooltipTrigger variant="outline">Hover for details</TooltipTrigger>
<TooltipPortal>
<TooltipContent side="right" align="start" sideOffset={10}>
<TooltipArrow />
Prefers the right side and aligns to the start of the trigger.
</TooltipContent>
</TooltipPortal>
</Tooltip>
</TooltipProvider>
);
}Accessibility#
TooltipContentusesrole="tooltip".TooltipTriggerreceivesaria-describedbypointing to the tooltip.- A tooltip is supplemental. Keep the trigger's own accessible name with
aria-labelor visible text; do not use the tooltip as the only label. - Tooltips appear for pointer hover and keyboard focus. Do not hide essential information behind a tooltip, because touch users may not discover it.
- For an information icon that reveals interactive content, prefer a Popover
with
openOnHoverso touch users can also click it. - Escape closes the tooltip.
- The tooltip respects
prefers-reduced-motionfor its open and close animation.
Props#
TooltipProvider#
| Prop | Type | Default |
|---|---|---|
delay | number | 500 |
| Shared hover and focus delay before opening. | ||
closeDelay | number | 0 |
| Shared delay before closing. | ||
timeout | number | 400 |
| Window in which the next tooltip opens instantly. | ||
Tooltip#
| Prop | Type | Default |
|---|---|---|
open | boolean | — |
| Controlled open state. | ||
defaultOpen | boolean | false |
| Initial open state for uncontrolled usage. | ||
onOpenChange | (open, eventDetails) => void | — |
| Called when the tooltip requests an open state change. | ||
disabled | boolean | false |
| Prevents the tooltip from opening. | ||
TooltipTrigger#
| Prop | Type | Default |
|---|---|---|
delay / closeDelay | number | — |
| Overrides the provider timing for this trigger. | ||
closeOnClick | boolean | true |
| Closes the tooltip when the trigger is clicked. | ||
render | ReactElement | — |
| Replaces the default ghost Button, for example with an IconButton or a custom element. | ||
aria-describedby | string | — |
| Merged with the tooltip ID. | ||
TooltipContent#
| Prop | Type | Default |
|---|---|---|
side | 'top' | 'bottom' | 'left' | 'right' | 'inline-start' | 'inline-end' | 'top' |
| Side of the trigger the tooltip is placed on. | ||
align | 'start' | 'center' | 'end' | 'center' |
| Alignment relative to the trigger. | ||
sideOffset | number | 6 |
| Distance between the trigger and the tooltip. | ||
alignOffset | number | 0 |
| Offset along the alignment axis. | ||
width / minWidth / maxWidth | CSSProperties values | — |
| Controls tooltip width. The default maximum is 15rem (240px). | ||
maxHeight | CSSProperties value | — |
| Controls the tooltip height before it scrolls. | ||
native attributes | Base UI Tooltip Popup props | — |
| Class names, data attributes, and refs are forwarded to the popup. | ||
Related#
- Popover for interactive floating content.
- Icon Button for icon-only triggers.
- Button for regular triggers.