Button
Last Updated: June 2025Buttons allow users to trigger actions or navigate to new surfaces within the product. They come in a variety of styles and sizes to support clear hierarchy when constructing a UI.
Source CodeAnatomy
link- 1Container
- 2Prefix
- 3Label
- 4Suffix
- 5Alert Badge
Variants
linkPrimary
Highest emphasis, solid accent fill. Use once per view for the main action.
Secondary
Medium emphasis, outlined accent. Pairs with Primary for the secondary action.
Tertiary
Low emphasis, text-only accent. For subtle or inline actions.
Neutral
Neutral surface with a border. For actions that shouldn't carry accent color.
Danger Primary
Solid destructive fill. Highest-emphasis irreversible action — confirm first.
Danger Secondary
Outlined destructive. Medium-emphasis destructive action.
Danger Tertiary
Text-only destructive. Low-emphasis destructive action inline.
Sizes
linkButtons support 3 sizes: S, M, and L.
Usage Guidelines
linkWhen to use
- •To trigger an immediate action (submit, save, delete).
- •As the primary call-to-action in a form or dialog.
- •When the action navigates the user but feels like a command.
When not to use
- •For navigation between pages — use a Link instead.
- •When the action is destructive without confirmation — use a dialog first.
Use one Primary button per view for the main action.
Don't use multiple Primary buttons — it dilutes hierarchy.
Use a Danger variant with an explicit destructive label.
Don't use vague labels on Danger buttons — always describe the consequence.
Behaviors
linkLoading state
- •Set loading=true to replace icon with Spinner and disable interaction.
- •The button width is preserved during loading to avoid layout shift.
Disabled state
- •Set disabled=true to prevent interaction.
- •Disabled buttons are not focusable.
Content Guidelines
linkLabels
- •Use sentence case ('Save changes', not 'Save Changes').
- •Start with a verb ('Delete', 'Add member', 'Export CSV').
- •Keep labels under 3 words where possible.
Icon usage
- •Use icons to reinforce meaning, not replace labels.
- •Prefer icon-only buttons (IconButton) when space is very constrained.
Accessibility
linkText & Labels
- •Always provide a visible label or aria-label.
- •For icon-only usage, use IconButton with aria-label.
ARIA attributes
- •aria-disabled communicates disabled state without removing focus.
- •aria-pressed for toggle behavior.
Keyboard Support
- •Tab → focus the button.
- •Space / Enter → activate.
WCAG Compliance Standards
FAQs
linkWhen should I use danger variants?
Use Danger Primary for irreversible actions (delete, revoke). Always confirm with a dialog first.
Can I use an icon without a label?
Use IconButton instead — it's optimized for icon-only use with proper accessibility.
How do I handle async actions?
Set loading=true while the action is in flight. The button disables itself and shows a spinner.