Button

Common Button Variants

Size Variants

Shape Variants

Experiment with border-radius values using our Border Radius Generator:

• Rounded (4–8px): Professional, enterprise feel
• Pill (9999px): Friendly, modern, consumer-facing
• Square (0px): Brutalist or highly structured layouts

Button Properties

Important: Always set type="button" explicitly. Browsers default to type="submit" inside forms, which causes accidental form submissions — one of the most common button bugs in production.

Design Token Mappings

Buttons touch almost every token category. Here's how they map. For a deeper dive on tokens, read our Design Tokens Complete Guide.

Use our Color Palette Generator to create cohesive button color sets, and the Shadow Generator for elevation values.

Interactive States

Focus Ring Best Practices

Use a 2px solid ring with a 2px offset from the button edge. The ring color should have at least 3:1 contrast against the surrounding background (WCAG 2.1 SC 1.4.11). Test with our Contrast Checker.

button:focus-visible {
  outline: 2px solid var(--color-focus-ring);
  outline-offset: 2px;
}

WCAG Requirements

ARIA Attributes

• Use native <button> — it has the button role built in. Avoid <div role="button"> unless absolutely necessary (you then need to handle Enter, Space, and focus yourself).
• Icon-only buttons: Add aria-label="Delete item" or wrap with visually-hidden text.
• Toggle buttons: Use aria-pressed="true|false".
• Loading state: Add aria-busy="true" and optionally aria-label="Saving, please wait".
• Disabled: Prefer aria-disabled="true" over the disabled attribute so screen readers can still discover and announce the button.

Keyboard Interaction

For deeper accessibility patterns, see our WCAG Practical Guide and Keyboard Accessibility Guide.

Do's

• ✅ Use a clear, verb-first label. "Save changes" not "Changes" or "OK". The label should describe the action.
• ✅ Limit to 2–3 button variants per page. One primary, one secondary, maybe a ghost. More than that creates visual noise.
• ✅ Place the primary action on the right in button pairs (e.g., "Cancel" left, "Submit" right) — this follows the natural reading flow in LTR languages.
• ✅ Show a loading state during async operations. Never let users wonder if their click registered.
• ✅ Keep button widths consistent within a group. Use min-width or full-width in mobile layouts.

Don'ts

• ❌ Don't use buttons for navigation. Use <a> tags. If it goes to a URL, it's a link.
• ❌ Don't disable buttons without explanation. If a form isn't valid, show validation errors instead. Disabled buttons with no context frustrate users.
• ❌ Don't use "Click here" as a label. It's meaningless to screen readers and tells users nothing about the action.
• ❌ Don't put two primary buttons side by side. If everything is important, nothing is.
• ❌ Don't rely on color alone to distinguish destructive buttons. Add an icon (trash, warning) or use clear labeling like "Delete permanently".

Content Guidelines

• Labels should be 2–4 words. If you need more, reconsider your UX.
• Use sentence case ("Save changes") not title case ("Save Changes") — it reads more naturally.
• For destructive actions, be specific: "Delete project" not just "Delete".

Learn more about button styling in our CSS Buttons guide and experiment live with our Button Generator.

Cross-System Comparison

Notable Approaches

Material 3 introduced "Tonal" buttons — a middle ground between filled and outlined that uses a lighter shade of the primary color. This is excellent for secondary actions that need more emphasis than an outline but less than a filled button. Consider adopting this in your design system if you find the primary/secondary/ghost trio isn't granular enough.

Shadcn/ui leverages the Radix Slot component via asChild, allowing you to render a button's styles on any element — perfect for when you need a button that's actually a <Link> under the hood.

Radix Primitives doesn't provide a button primitive because native <button> already has the right semantics. Radix focuses on complex widgets (Dialog, Popover, etc.) where native elements fall short.

Ant Design bundles a loading prop directly into the button component, including an automatic spinner — a pragmatic approach that reduces boilerplate in enterprise apps.

For more on building component libraries, read our Building Component Libraries guide.