When to use
- Naming icon-only buttons in a toolbar: Bold, Italic, Insert link.
- Showing the keyboard shortcut for an action next to its name: Bold ⌘B.
- A row of controls people sweep across with the pointer: after the first tooltip, the rest appear at once.
When not to use
- Anything people need in order to use the page, such as instructions, errors or why something is disabled: put it in the UI, because touch and screen reader users never see a tooltip.
- Content with links, buttons or more than a short line: use a Popover.
- Explaining a disabled radio or setting: write it in the option's description, as Radio Group does.
Installation
pnpm dlx shadcn add https://eased.dev/r/tooltip.jsonnpx shadcn add https://eased.dev/r/tooltip.jsonyarn dlx shadcn add https://eased.dev/r/tooltip.jsonbunx --bun shadcn add https://eased.dev/r/tooltip.jsonThe command adds Tooltip, everything it builds on and Eased’s tokens to your project.
Install the dependencies
pnpm add @base-ui/reactnpm install @base-ui/reactyarn add @base-ui/reactbun add @base-ui/reactAdd the Eased pieces it builds on
Copy each item’s files the same way, or install them with the CLI:
Copy the source into your project
components/eased/tooltip/tooltip.tsxTSX "use client";import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";import type { ReactElement, ReactNode } from "react";import { FloatingLayer, floatingSurface, type FloatingAlign, type FloatingSide } from "../_primitives/floating/floating";import { Kbd } from "../kbd/kbd";export type TooltipProviderProps = { /** How long the pointer must rest on the first trigger before its tooltip opens, ms. Default 400. */ delay?: number; /** How long a tooltip stays after the pointer leaves, ms. Default 0. */ closeDelay?: number; /** After a tooltip closes, the next one within this window opens instantly and unanimated, ms. Default 400. */ timeout?: number; children: ReactNode;};/** * A delay group. Inside it the first tooltip waits `delay`; while the pointer sweeps on to * neighbouring triggers the rest appear at once, with no animation. */export function TooltipProvider({ delay = 400, closeDelay = 0, timeout = 400, children }: TooltipProviderProps) { return ( <BaseTooltip.Provider delay={delay} closeDelay={closeDelay} timeout={timeout}> {children} </BaseTooltip.Provider> );}export type TooltipProps = { /** The label. Keep it short; the trigger still needs a matching `aria-label`. */ content: ReactNode; /** Keys shown after the label as `Kbd` caps, one per key: `["⌘", "B"]`, or `"Esc"` for one key. */ shortcut?: string | string[]; /** The trigger: one focusable element that accepts a ref, usually an icon button. */ children: ReactElement; /** Preferred side; flips on collision. Default "top". */ side?: FloatingSide; align?: FloatingAlign; /** Gap to the trigger, px. Default 6. */ sideOffset?: number; /** Rest time before opening, ms. Unset: the provider's delay (400), or Base UI's 600 outside a provider. */ delay?: number; closeDelay?: number; /** Close when the trigger is clicked. Default true. */ closeOnClick?: boolean; open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean) => void; disabled?: boolean; /** Stacking order. Default 50; raise it inside a higher layer such as a dialog. */ zIndex?: number; /** Appended to the tooltip's classes. */ className?: string;};/** * A short visual label for mouse and keyboard users. It opens after the pointer rests (or on * keyboard focus), enters 3px toward its trigger from the trigger's origin, and never shows on touch. */export function Tooltip({ content, shortcut, children, side = "top", align = "center", sideOffset, delay, closeDelay, closeOnClick = true, open, defaultOpen, onOpenChange, disabled, zIndex, className = "",}: TooltipProps) { const keys = typeof shortcut === "string" ? [shortcut] : shortcut; return ( <BaseTooltip.Root open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange ? (next) => onOpenChange(next) : undefined} disabled={disabled} > <BaseTooltip.Trigger render={children} delay={delay} closeDelay={closeDelay} closeOnClick={closeOnClick} /> <FloatingLayer parts={BaseTooltip} role="tooltip" side={side} align={align} sideOffset={sideOffset} zIndex={zIndex} className={`${floatingSurface} flex max-w-[min(16rem,var(--available-width))] items-center gap-2 rounded-control-sm px-2.5 py-1 text-ui-sm text-pretty ${className}`} > <span className="min-w-0">{content}</span> {keys && keys.length > 0 && ( // The label already names the action; the caps are a visual hint, not read twice. <span aria-hidden className="-mr-1 inline-flex shrink-0"> <Kbd keys={keys} listen={false} /> </span> )} </FloatingLayer> </BaseTooltip.Root> );}Keep the folder layout
The files import each other by relative path (
../lib/motion), so keep each one at the path shown, undercomponents/eased/.
Usage
import { Tooltip, TooltipProvider } from "@/components/eased/tooltip/tooltip";export function FormattingToolbar() { return ( <TooltipProvider> <Tooltip content="Bold" shortcut={["⌘", "B"]}> <button type="button" aria-label="Bold"><BoldIcon /></button> </Tooltip> <Tooltip content="Italic" shortcut={["⌘", "I"]}> <button type="button" aria-label="Italic"><ItalicIcon /></button> </Tooltip> </TooltipProvider> );}Wrap a toolbar, or your whole app, in one TooltipProvider so neighbouring tooltips share a delay group.
Examples
Below the trigger, with one key
A string shortcut shows a single key.
<Tooltip content="Close panel" shortcut="Esc" side="bottom"> <Button size="icon-sm" variant="ghost" aria-label="Close panel"><CloseIcon /></Button></Tooltip>Inside a dialog
Dialogs sit at z-index 50, the tooltip's default, so raise zIndex for a trigger inside one.
<Tooltip content="Copy link" zIndex={60}> <Button size="icon-sm" aria-label="Copy link"><LinkIcon /></Button></Tooltip>API reference
TooltipProvider
| Prop | Type | Default | Description |
|---|---|---|---|
delay | number | 400 | How long the pointer must rest on the first trigger before its tooltip opens, ms. |
closeDelay | number | 0 | How long a tooltip stays after the pointer leaves, ms. |
timeout | number | 400 | After a tooltip closes, the next one within this window opens at once with no animation, ms. |
Tooltip
| Prop | Type | Default | Description |
|---|---|---|---|
content | ReactNode | The label. Keep it short; the trigger still needs a matching aria-label. | |
shortcut | string | string[] | Keys shown after the label as Kbd caps: ["⌘", "B"], or "Esc" for one key. | |
children | ReactElement | The trigger: one focusable element that accepts a ref, usually an icon button. | |
side | "top" | "bottom" | "left" | "right" | "inline-start" | "inline-end" | "top" | Preferred side; flips on collision. |
align | "start" | "center" | "end" | "center" | |
sideOffset | number | 6 | Gap to the trigger, px. |
delay | number | the provider's | Rest time before opening, ms. Base UI's 600 outside a provider. |
closeDelay | number | the provider's | |
closeOnClick | boolean | true | Close when the trigger is clicked. |
open / defaultOpen | boolean | Controlled or uncontrolled open state. | |
onOpenChange | (open: boolean) => void | ||
disabled | boolean | Never open. | |
zIndex | number | 50 | Raise it inside a higher layer such as a dialog. |
className | string | "" | Appended to the tooltip's classes. |
The tooltip is at most 16rem wide and wraps longer text.
Keyboard
| Key | Action |
|---|---|
Tab | Focusing the trigger opens its tooltip. |
Esc | Closes the tooltip. |
Accessibility
- Tooltips are supplementary visual labels. Give the trigger an
aria-labelthat matchescontent, so screen reader users get the same name. - The shortcut caps are hidden from screen readers; the label already names the action.
- Base UI disables tooltips on touch, where there is no way to reveal one before tapping.
- Keyboard focus opens the tooltip as well as hover.
Motion
The tooltip grows from its trigger: it scales from 0.97 at the trigger's origin and travels 3px toward its resting place on the snappy spring, while its opacity fades in over 150ms. It leaves in 100ms, travelling half as far, with no overshoot, and closing during the open turns around mid-flight. Inside a provider, the first tooltip waits 400ms; while the pointer sweeps on to neighbouring triggers, the rest appear and leave at once with no animation. Reduced motion keeps only a 100ms fade.
Notes for AI
Use Tooltip to name icon-only buttons and show their shortcuts, with one TooltipProvider around the toolbar or app. The child must be a single focusable element that accepts a ref, with its own aria-label.
Do not put essential information, links or buttons in a tooltip: use a Popover or text in the UI instead. Do not add your own delay or animation; the provider and floating layer handle both.
Related components
- Animated Popover: an interactive panel that touch and screen reader users can reach.
- Keyboard Shortcut Key (Kbd): the key caps the shortcut uses.
- Animated Hover Card