React Tooltip component

Preview

<Tooltip content="Save your changes">
  <Button>Save</Button>
</Tooltip>

Usage

Use when

Naming icon-only buttons
Showing text that had to be truncated
Surfacing a keyboard shortcut
One line of help, no more

Avoid when

Help longer than a line — use Popover
Anything the user must not miss — use Alert
Content they need to click — use Popover or Menu
Touch-first screens, where there is no hover

Implementation notes

Under 80 characters
Sentence case, no trailing period
Never just repeat the visible label
Always leave a non-hover path to the same information
Put a keyboard shortcut in shortcut, not in the text
A disabled control is wrapped automatically so its tip still shows on hover
Wrap a toolbar in Tooltip.Provider to share one rest and warm window
contentProps sets attributes on the tip surface

Installation

pnpm add @usefragments/ui

The npm package stays managed by your package manager. Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Anatomy

Import Tooltip once, then compose its parts with dot notation.

Tooltip.Provider

Examples

Positions

Four sides; it flips if the edge is too close.

import { Stack } from '@usefragments/ui';

<Stack direction="row" gap="md" align="center" wrap>
  <Tooltip content="Top tooltip" side="top">
    <Button variant="soft">Top</Button>
  </Tooltip>

With Shortcut

A shortcut follows the text at the regular weight.

<Tooltip content="Undo" shortcut="⌘Z">
  <Button variant="ghost">Undo</Button>
</Tooltip>

With Content Props

contentProps lands on the popup element itself.

<Tooltip
  content="Styled through contentProps"
  contentProps={{ id: 'custom-tooltip-popup' }}
>
  <Button variant="soft">Custom popup</Button>
</Tooltip>

On a disabled control

The tip still explains why the control is off.

<Tooltip content="Pick canonical components first">
  <Button disabled>Activate workspace rules</Button>
</Tooltip>

API reference

Component props
Prop	Type	Default	Description
`align`	`TooltipAlign \| undefinedcenterstartend`	`center`	Alignment along the side
`children`Required	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>`	Not set	The element that triggers the tooltip
`closeDelay`	`number \| undefined`	`0`	Delay before hiding (ms)
`closeOnClick`	`boolean \| undefined`	`true`	Whether pressing the trigger closes the tip until the pointer leaves
`content`Required	`React.ReactNode`	Not set	Content to display in the tooltip
`contentProps`	`TooltipContentProps \| undefined`	Not set	Props for the tip surface: id, className and data-* attributes
`defaultOpen`	`boolean \| undefined`	`false`	Default open state
`delay`	`number \| undefined`	`500`	Rest before opening (ms). Defaults to the provider's delay, or 500 with a 300ms warm window after another tip closes
`disabled`	`boolean \| undefined`	`false`	Render the child alone, with no tip
`onOpenChange`	`((open: boolean) => void) \| undefined`	Not set	Callback when open state changes
`open`	`boolean \| undefined`	Not set	Controlled open state
`Provider.children`Required	`React.ReactNode`	Not set	—
`Provider.closeDelay`	`number \| undefined`	Not set	Delay before hiding (ms).
`Provider.delay`	`number \| undefined`	Not set	Rest before the first tip opens (ms).
`Provider.timeout`	`number \| undefined`	Not set	How long after a tip hides the next one opens at once (ms).
`shortcut`	`React.ReactNode`	Not set	A keyboard shortcut shown after the text, such as ⌘K
`side`	`TooltipSide \| undefinedtopbottomleftright`	`top`	Which side to show the tooltip

Accessibility

Opens on keyboard focus, not only hover
The open delay stops tooltips flashing while the pointer crosses the screen
Do not put anything critical here — treat it as a hint, not a label

PopoveralternativeUse Popover for interactive or longer content
AlertalternativeUse Alert for critical information that must be visible

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.