Tooltip
Popup overlay that shows supplementary details on element hover.
The Tooltip primitive provides accessible, keyboard-aware helper label overlays that appear on mouse hover or element focus.
Quick Start
Wrap an interactive element to attach a hover/focus description helper bubble:
import { Tooltip, Button } from 'boltdocs/primitives'
export default function App() {
return (
<Tooltip content="Permanently delete the project metadata files" delay={300}>
<Button className="px-4 py-2 bg-red-600 text-white rounded-lg hover:bg-red-700">
Delete Repository
</Button>
</Tooltip>
)
}
Composable Subcomponents
If you need full control over the trigger flow lifecycle, you can compose tooltips using the nested components:
| Component | HTML Tag | Description | Props |
|---|---|---|---|
Tooltip.Root / Tooltip | Wrapper | Auto-trigger wrapper handling hover delays and states. | Tooltip Props |
Tooltip.Content | <div> | Floating container rendering the tooltip description box and overlay arrow. | TooltipContent Props |
Component Props
Tooltip Props
| Property | Type | Default | Description |
|---|---|---|---|
content | ReactNode | Required | The text or graphic content to render inside the popup tooltip. |
children | ReactElement | Required | The interactive trigger target element (must support hover/focus event hooks). |
delay | number | 500 | Hover delay duration in milliseconds before the tooltip appears with transition. |
closeDelay | number | 0 | Delay duration in milliseconds before the tooltip disappears on mouse leave. |
placement | 'bottom' | 'top' | 'left' | 'right' | 'top' | Preferred alignment positioning side. |
Tooltip.Content Props
Inherits the standard React Aria TooltipProps properties:
| Property | Type | Default | Description |
|---|---|---|---|
className | string | undefined | Custom utility CSS class overrides. |
style | CSSProperties | undefined | Inline style overrides. |
Customization & states
Tooltip wraps React Aria's Tooltip. The trigger (Tooltip.Root / Tooltip) only owns behavior — hover delays, placement, and open/close. All visuals belong to the theme through Tooltip.Content's className (a plain string or a render function receiving the placement), and RAC mirrors the animation and placement states onto the content as data-* attributes.
| State / Slot | Mechanism |
|---|---|
Tooltip.Content className | String passthrough (or function receiving { placement, isEntering, isExiting }) |
data-entering / data-exiting | Present during open/close — use data-entering: / data-exiting: animation variants |
data-placement | top / bottom / left / right — placement-aware offsets via data-[placement=top]: |
Tooltip props | delay, closeDelay, placement — behavior only |
OverlayArrow | Themed arrow rendered inside Tooltip.Content |
Tailwind v4:
<Tooltip.Root>
<Button className="px-4 py-2 rounded-lg bg-primary-500 text-white">
Hover me
</Button>
<Tooltip.Content className="data-entering:animate-in data-entering:fade-in data-entering:zoom-in-95
data-[placement=top]:slide-in-from-bottom-1
rounded-md bg-surface text-body ring-1 ring-subtle px-2.5 py-1.5">
Helpful detail
</Tooltip.Content>
</Tooltip.Root>
