Choosing components

Overlay content (dialogs, menus, drawers)

Key differences:

• Dialog vs Alert Dialog: Dialog can be dismissed with Escape or backdrop click. Alert Dialog requires an explicit user action (confirm/cancel) to proceed and is intended for destructive or irreversible operations.
• Dialog vs Drawer: Drawer extends Dialog with gesture support, snap points, and indent effects. Use Drawer when you need those; otherwise a positioned Dialog is sufficient. Dialog does not support gestures.
• Menu vs Popover: Menu is for a list of actions with keyboard navigation (arrow keys, type-ahead). Use Popover for general interactive content (see next section).

Contextual hints and notifications (Popover, Tooltip, Toast)

These three are often confused. Use the table and key differences below to decide.

Key differences:

• Popover — An accessible popup anchored to a button. Use when the trigger’s purpose is to open the popup and the popup can contain interactive content (buttons, links, form fields). Popover is non-modal and can open on click or hover (openOnHover). Use Popover instead of Tooltip when the content must be available to touch or screen reader users (e.g. infotips on an info icon).

• Tooltip — A popup that appears when an element is hovered or focused, showing a hint for sighted users. Use when you need a short, non-interactive label or hint for an element whose main purpose is something else (e.g. an icon button). Tooltips act as supplementary visual labels; they are not accessible to touch or screen reader users. The trigger must have an accessible name (e.g. aria-label). If the description is important for everyone, use inline text or Popover instead. See the Tooltip documentation for alternatives to tooltips.

• Toast — Generates toast notifications. Use when you need to notify the user about something that just happened (e.g. saved, error, copied) without a specific trigger. Toasts are temporary and can stack; they can also be anchored for contextual feedback. Do not use Toast for content tied to a specific control—use Tooltip or Popover for that.

Actions and toggles

Key differences:

• Button vs Toggle: Button triggers an action. Toggle indicates a pressed/unpressed state (e.g. bold in a toolbar) and uses aria-pressed. Do not use Button for links—style an <a> element directly.
• Toggle Group vs Radio: Both allow exclusive selection. Toggle Group is for toolbar-style actions; Radio is for form fields. Toggle Group also supports multi-select.

On/off, choice, and range controls

Key differences:

• Switch vs Checkbox: Both are boolean form controls. Switch indicates whether a setting is on or off. Checkbox is for selected/unselected and is typically submitted with a form.
• Toggle vs Switch: Toggle is for toolbar actions (e.g. bold/italic) and uses aria-pressed. Switch is for form settings and uses role="switch".

Choosing from a list

Key differences:

• Select vs Combobox: Select is not filterable (aside from keyboard typeahead). Prefer Combobox when the number of items is large enough to warrant filtering. Use Select instead of Combobox when no input is rendered (listbox-only pattern).
• Combobox vs Autocomplete: Combobox restricts the value to predefined items. Autocomplete allows free-form text; suggestions only optionally autocomplete. Use Combobox when the selection must be remembered and the value cannot be custom; use Autocomplete for search widgets or filterable command pickers.

Tabs, accordions, and collapsible content

Key differences:

• Tabs vs Accordion: Tabs show one panel at a time with tab list navigation. Accordion is a set of collapsible panels with headings and can have multiple panels open.
• Accordion vs Collapsible: Accordion manages a group of sections with shared state. Collapsible is a single panel controlled by a button.

Form structure and inputs

Form is composed with Field. See the forms guide for naming controls, validation, and integration with React Hook Form or TanStack Form.

Navigation

Progress and status

Key differences: Progress displays task completion (e.g. upload). Meter displays a value within a known range (e.g. capacity, rating), not task progress. For when to use Toast vs Tooltip or Popover, see the Popover, Tooltip, and Toast section above.

Avatar and toolbar