Tooltip
A short text label anchored to its trigger that never takes focus.
Installation
npx shadcn@latest add @flyingsalmon/tooltipUsage
import { Share2 } from 'lucide-react'
import { Button, ButtonSize, ButtonVariant } from '@/components/ui/button'
import { Tooltip } from '@/components/ui/tooltip'
export function TooltipUsage() {
return (
<Tooltip content="Share the trip">
<Button
variant={ButtonVariant.Outline}
size={ButtonSize.Icon}
aria-label="Share the trip"
icon={<Share2 />}
/>
</Tooltip>
)
}Examples
Placement
side picks the edge and align lines the tooltip up along it. A tooltip that would leave the viewport flips to the other side.
A keyboard shortcut
Type the shortcut into the string. The tooltip is the one place a shortcut belongs, and the label stays plain text.
Any focusable child
A tooltip wraps any single element, not only a Button, as long as the element is focusable. An Avatar takes no focus of its own, so this one adds tabIndex at the call site.
Guidelines
When to use
- To name an icon-only control: "Add a place", "Share the trip".
- To add a keyboard shortcut to a label.
- To clarify something with one short sentence that the page can do without.
When not to use
- Use Icon tooltip for an icon that only explains itself and is not a control. Icon tooltip makes it focusable and names it.
- Use Alert for a reason, a result, or an error. These must be seen, so they go on the page next to what they describe.
- Use Dialog for content with links, buttons, or images. A tooltip closes when the pointer leaves, so nothing inside it can be used.
Do and don’t
- DoKeep it to one or two sentences the traveller does not need in order to act. If they must read it, put it on the page.A tooltip is out of reach on touch, and a screen reader that never focuses the trigger never hears it.
- Don’tHide why a control is disabled in a tooltip. Write the reason next to the control.A disabled control cannot open a tooltip, and the reason is the one thing the traveller needs to move on.
- Don’tPut a tooltip on every row.A few explained terms on a screen stand out. One on every row is noise nobody hovers.
Accessibility
| Key | Description |
|---|---|
| Tab | Moves focus onto the trigger, which opens the tooltip. Tabbing away closes it. |
| Escape | Closes the tooltip. Inside a dialog, it closes the tooltip before the dialog. |
The tooltip never takes focus and draws no ring of its own; the trigger keeps whichever ring it already has. The pointer can cross the gap from the trigger onto the tooltip without closing it, and any pointer press closes it.
The tooltip sets aria-describedby on the trigger and renders a node with role="tooltip", so the trigger keeps its own name and the tooltip only describes it. An icon-only button therefore needs an aria-label of its own.
A disabled button fires no pointer or focus events, so a tooltip on it never opens. An element that cannot take focus never shows its tooltip to a keyboard traveller.
API
Tooltip
| Prop | Type | Default | Description |
|---|---|---|---|
| content | string | Required | The label. Text only. |
| children | ReactElement | Required | One focusable element that anchors the tooltip. The component adds no tabIndex, so give a text span tabIndex={0}. An icon-only button keeps its own aria-label as well. |
| side | TooltipSide | TooltipSide.Top | Which edge of the trigger the tooltip opens from. It flips when there is no room. |
| align | TooltipAlign | TooltipAlign.Center | How the tooltip lines up along that edge. |
| open | boolean | – | The controlled open state. |
| defaultOpen | boolean | false | The initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | – | Called when the tooltip opens or closes. |
TooltipProvider
Mount it once at the app root. It fixes the open delay for every tooltip.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | Required | The app. |