Choosing components
Choose by what the user is trying to do, not by visual resemblance. Start with the least complex component that preserves native semantics.
Common decisions
Section titled “Common decisions”| If the user needs to… | Choose | Key distinction |
|---|---|---|
| Navigate somewhere | Link | Button performs an action. Use one primary Button per local action group, secondary for support, and tertiary for low emphasis. medium is the default size; small is for dense supporting controls. |
| See persistent contextual status | Alert | Toast announces a short-lived application outcome away from a specific content region. Use error for failures, warning for risk, success for completion, and info for neutral updates. |
| Toggle a live setting | Switch | Checkbox represents independent selection or agreement, often for later submission. |
| Choose one visible option | Radio | Select keeps longer predefined lists compact; Checkbox allows multiple independent choices. |
| Complete a focused modal task | Dialog | SideSheet suits longer supporting work; BottomSheet suits short, touch-oriented tasks. Prefer page content when modality is unnecessary. |
| Reveal sections in place | Accordion | Tabs switch among peer panels where one remains visible. Use manual tab activation when loading a panel is expensive. |
| Browse a short visual sequence | Carousel | Use a normal list or grid when comparison or scanning matters. Pagination changes a larger application-owned result set. |
| Show ordered workflow progress | ProgressIndicator | It reports status and is not navigation; provide separate Back and Continue actions. |
| Explain a control briefly | Tooltip | Use visible text for essential instructions and helper/error text for form guidance. Tooltip content is non-interactive. |
Remaining catalog
Section titled “Remaining catalog”- Input collects a single-line native value; Textarea is for free-form multi-line content.
- Rating is specifically a one-to-five-star choice; use Radio for other labelled scales.
- Breadcrumb shows the current location in a hierarchy, not a menu of unrelated destinations.
- Tag is passive metadata or status. Use Button or Link if the label is interactive.
- Card visually groups related passive content. Plain semantic HTML is enough when no grouping treatment is needed.
- Heading follows document structure; choose its level by hierarchy, never desired visual size.
- Image adds responsive sources and BlurHash behavior. Use native image markup when upgrade-dependent behavior is unnecessary.
- Icon renders a known symbol. Prefer text when a symbol is ambiguous, and give icon-only controls an accessible name.
Once selected, read the component page for its exact API, accessibility contract, and unsupported behavior. Do not copy variants or props from another design system.