Overlays
Which component to use for something that floats above the page — a modal, a side panel, a hint, a preview. Find the job, take the component, and read the “not when” before you commit: it names the thing people reach for by mistake, and what to use instead.
At a glance
| Job | Use | Not when | Instead | Because |
|---|---|---|---|---|
| Stop the page for a decision the person has to make now | Dialog | A longer panel of detail or navigation that slides in beside the page | Drawer | A drawer is a modal side panel with a pinned head and a scrolling body; a dialog is a centred decision. |
| A few controls anchored to a button, with the page still usable | Popover | A popover is non-modal and does not trap Tab; a dialog takes the page over. | ||
| An agent proposes a change in a conversation and a person must approve it | ConfirmCard | The confirm card sits inline, stays as a record once answered, and states spend before the button. | ||
| Reporting something that needs no answer | Alert | An alert can be read past; a dialog demands dismissal. | ||
| Searching for a command or place across the app | CommandPalette | The palette is a dialog built for typing and choosing; do not rebuild it from Dialog. | ||
| Slide a modal panel in from the side of the page | Drawer | A short decision that blocks the page | Dialog | A dialog is a centred decision with actions; a drawer is a panel to read or move around in. |
| The side pane should stay open while the person works in the page | Split | A split pane is part of the layout and does not trap focus; a drawer is modal. | ||
| A small panel anchored to the control that opened it | Popover | A popover floats beside its trigger and leaves the page usable. | ||
| Preview what a link, a name or an id leads to, on pointing or focus | HoverCard | The person has to act inside the panel | Popover | Focus does not move into a hover card and Tab does not enter it; anything to press belongs in a popover. |
| One line that describes a control | Tooltip | A tooltip is the control's description; a hover card is a preview of somewhere else. | ||
| A citation marker in prose | Citation | The citation draws the marker and its SourceCard; the hover card is only the surface it opens in. | ||
| Open a small panel of content or controls beside the button that opened it | Popover | A list of actions or choices | Menu | A menu has the menu-button keyboard contract and closes on choice; a popover is free content. |
| A preview that opens by pointing or focus and needs no action inside | HoverCard | A hover card opens on dwell and focus; a popover waits for a click. | ||
| One line describing a control | Tooltip | A tooltip is a description wired by aria-describedby, not a panel. | ||
| The person must finish or cancel before going on | Dialog | A popover you cannot Tab out of is a dialog wearing the wrong clothes. | ||
| Describe a control in a line, on hover or focus | Tooltip | The words are the control's only name | Button | A tooltip describes via aria-describedby; an icon-only button needs its own aria-label. |
| The hint is load-bearing — something the person must read to fill a field | Field | A field hint is always on screen; a tooltip is only there for someone who points at it. | ||
| A preview of what a link or id leads to | HoverCard | A hover card holds a card of content; a tooltip holds a line. | ||
| Controls or a form inside the floating panel | Popover | Nothing in a tooltip can be pressed. |
Dialog
Stop the page for a decision the person has to make now.
Use when
- A confirmation before something irreversible — list what it will write in the body, and turn
dismissOnBackdropoff. - A short, self-contained task that must finish or be cancelled before the page is usable again.
- Give it a
tonewhen the decision is destructive, so the surface says so and not only the prose.
Not when
- A longer panel of detail or navigation that slides in beside the page →
Drawer. A drawer is a modal side panel with a pinned head and a scrolling body; a dialog is a centred decision. - A few controls anchored to a button, with the page still usable →
Popover. A popover is non-modal and does not trap Tab; a dialog takes the page over. - An agent proposes a change in a conversation and a person must approve it →
ConfirmCard. The confirm card sits inline, stays as a record once answered, and states spend before the button. - Reporting something that needs no answer →
Alert. An alert can be read past; a dialog demands dismissal. - Searching for a command or place across the app →
CommandPalette. The palette is a dialog built for typing and choosing; do not rebuild it fromDialog.
Drawer
Slide a modal panel in from the side of the page.
Use when
- The site links behind a
Hamburgeron a phone (side="end"), or a rail that becomes a drawer on small screens (side="start"). - Detail about one item — a source, a finding, a transcript — read beside the page, with
headerpinned and aPagerChipto step through the set. size="lg"for a reading width; it takes the whole screen on a phone.
Not when
- A short decision that blocks the page →
Dialog. A dialog is a centred decision with actions; a drawer is a panel to read or move around in. - The side pane should stay open while the person works in the page →
Split. A split pane is part of the layout and does not trap focus; a drawer is modal. - A small panel anchored to the control that opened it →
Popover. A popover floats beside its trigger and leaves the page usable.
HoverCard
Preview what a link, a name or an id leads to, on pointing or focus.
Use when
- A glance at what is behind a reference — a person behind a name, a requirement behind an id, a source behind a citation.
- Markers inside sanitised HTML you did not render in React: use
useDelegatedHoverCardon the container.
Not when
- The person has to act inside the panel →
Popover. Focus does not move into a hover card and Tab does not enter it; anything to press belongs in a popover. - One line that describes a control →
Tooltip. A tooltip is the control's description; a hover card is a preview of somewhere else. - A citation marker in prose →
Citation. The citation draws the marker and itsSourceCard; the hover card is only the surface it opens in.
Popover
Open a small panel of content or controls beside the button that opened it.
Use when
- A click opens a few controls or a short form anchored to its trigger — a date, a share setting, a run's detail.
- The page stays usable: Escape and a click outside close it, and Tab is not trapped.
size="lg"for a panel with a reading width of its own that scrolls inside itself.
Not when
- A list of actions or choices →
Menu. A menu has the menu-button keyboard contract and closes on choice; a popover is free content. - A preview that opens by pointing or focus and needs no action inside →
HoverCard. A hover card opens on dwell and focus; a popover waits for a click. - One line describing a control →
Tooltip. A tooltip is a description wired byaria-describedby, not a panel. - The person must finish or cancel before going on →
Dialog. A popover you cannot Tab out of is a dialog wearing the wrong clothes.
Tooltip
Describe a control in a line, on hover or focus.
Use when
- An icon button or a terse label needs a few words of description — "Copy link", "Last synced 4 minutes ago".
- Instead of a
titleattribute, which the operating system draws and touch and keyboards never reach.
Not when
- The words are the control's only name →
Button. A tooltip describes viaaria-describedby; an icon-only button needs its ownaria-label. - The hint is load-bearing — something the person must read to fill a field →
Field. A field hint is always on screen; a tooltip is only there for someone who points at it. - A preview of what a link or id leads to →
HoverCard. A hover card holds a card of content; a tooltip holds a line. - Controls or a form inside the floating panel →
Popover. Nothing in a tooltip can be pressed.
Other guides: Screens · Status and feedback · Navigation · Data · Input · Reading · Agents and live work
Generated from the when.ts beside each component — the same data the Claude Code plugin reads.