Button
Overview
Buttons trigger actions. Use them to let users submit, confirm, cancel, or initiate a task within the current context.
Sandbox
Anatomy
- Container — The clickable surface of the button.
- Label — Text describing the action. Required unless the button is icon-only.
- Leading icon (optional) — An icon placed before the label to reinforce the action.
- Trailing icon (optional) — An icon placed after the label, used for directional or menu actions.
- Icon (icon-only variant) — Replaces the label entirely; requires an accessible label.
Variants
Primary — The highest-emphasis button. Use for the main action in a view or dialog, such as Save or Confirm. Only one primary button should appear per context.
Secondary — Medium emphasis. Use for supporting actions that matter but don't compete with the primary, such as Cancel or Edit.
Tertiary — Low emphasis. Use for inline or low-priority actions, such as View details or Learn more.
Flat — The lowest visual weight. Use in dense layouts or toolbars where a border or fill would create too much noise.
Destructive — Use when the action permanently removes or deletes something. The red color signals irreversibility. Always pair with a confirmation step.
Inverse — Use on dark or colored surfaces where standard button colors would not have sufficient contrast.
Usage
Use buttons to trigger actions within the current context. Don't use them for navigation that loads an entirely different view.
- Primary actions — the main task on a screen, like Save or Send. Keep to one per context.
- Secondary actions — supporting or reversible actions, like Cancel or Edit.
- Tertiary or flat buttons — inline or low-emphasis actions where a filled button would add too much visual weight.
Best Practices
| Do | Don't |
|---|---|
| Use clear, action-oriented labels like "Save," "Send," or "Retry" | Don't use vague labels like "Click here" or "Submit" without context |
| Keep one primary button per view or dialog | Don't place multiple primary buttons in the same context |
Include an aria-label for icon-only buttons | Don't use icon-only buttons without an accessible label |
| Use the Destructive variant for actions that permanently delete or remove | Don't use standard button styles for destructive actions |
| Keep labels short | Don't truncate button labels unless space is critically constrained |
Accessibility
- Provide accessible names via text, aria-label , or aria-labelledby.
- Ensure visible focus indicators for all interactive states.
- Maintain minimum 3:1 contrast ratio between adjacent button states.
- Buttons must be operable via keyboard and assistive technology.
- Communicate state changes (e.g., toggled/selected) programmatically.