Skip to main content

Button

Interactive button with emphasis, intent, fill, and size variants. Buttons trigger actions on the current page; links take users somewhere else. Emphasis, intent, and fill are independent axes that compose via multiple classes, so consumers can mix a semantic intent (info, warning, danger, success) with an emphasis weight (subtle, accent), a visual fill (solid, outline, ghost), and a size (xs, sm, md, lg, xl).

Emphasis and intent choose the palette - what the colors mean. Fill chooses how that palette is painted: solid makes the palette color the surface, outline traces it as a border over a transparent surface, and ghost drops the surface entirely and keeps only the label. Every fill renders every palette, so class="solid danger" is a filled destructive button and class="ghost danger" is the same palette with no surface at all.

Usage​

When to use

  • To trigger an action on the current page (submit a form, open a dialog, reveal content)
  • To confirm, cancel, or dismiss a user-initiated flow
  • To group related actions that sit together on a page

When not to use

  • To navigate between pages - use a link instead
  • For standalone navigation within running text - use a link
  • For purely decorative or informational elements

Do

  • Reserve the default (neutral) emphasis for the single most important action in a context
  • Use subtle for ancillary actions ("Cancel", "Preferences") so the eye lands on the main CTA
  • Write labels as concise verb phrases ("Save changes", "Launch mission")
  • Provide an aria-label when a button shows an icon only

Don't

  • Don't pair two neutral buttons in the same action group - downgrade the secondary one to subtle
  • Don't rely on color alone to communicate intent
  • Don't disable buttons without explaining why the action is unavailable

API​

Slots​

SlotRequiredDescription
contentYesVisible button text.

Props​

PropTypeDefaultDescription
typeEnum: button, submit, resetbuttonButton HTML type.
is_disabledboolean-Renders the disabled attribute.
is_loadingboolean-Adds aria-busy="true" for loading state.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.infoIntent-Informational message.
.warningIntent-Warning or caution.
.dangerIntent-Error, destructive, or critical.
.successIntent-Confirmation or completion.
.solidFillYesFilled surface; background and border rendered.
.outlineFill-Bordered surface; transparent background.
.ghostFill-No surface; text or icon only.
.xsSize-Extra small.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.xlSize-Extra large.
.roundedShape-Rounded corners.
.squareShape-Sharp corners.
.pillShape-Fully rounded ends.
.circleShape-Perfect circle.
.fluidLayout-Full-width, no max-width.
.animatedMotionYesHonors the animations option.
.stillMotion-Forces motion off regardless of the option.
.flatElevationYesNo elevation.
.raisedElevation-Slight elevation.

Examples​

Default​

Default button treatment for the most important action - the neutral emphasis at the default solid fill.

Emphasis and intent values​

The emphasis values (subtle, neutral, accent) and intent values (info, warning, danger, success).

Solid fill​

Solid fill paired with any emphasis or intent value. The palette color becomes the surface and the label flips to a color that reads on it.

Outline fill​

Outline fill paired with any emphasis or intent value. The palette color traces the border and stays on the label.

Ghost fill​

Ghost fill paired with any emphasis or intent value. Both the surface and the border are transparent, leaving the palette on the label alone. Hovering tints the surface with the palette's hover color; the border stays transparent in every state.

Sizes​

The five size values - xs, sm, the default md, lg, and xl.

Shapes​

The four shape values. square, rounded, and pill change the corner radius alone. circle also fixes the button to a disc the height of its size tier, so it is the one shape that expects an icon rather than a label.

Fluid​

The fluid layout value stretches the button to the full width of its container.

Icon button​

Button containing an icon before or after the label, and icon-only button with aria-label.

Disabled and loading​

Disabled state via the disabled attribute and loading state via aria-busy.

Accessibility​

  • WCAG 2.2 AA
  • Keyboard reachable via Tab, activatable by Enter and Space
  • Visible focus indicator on all interactive states
  • Disabled buttons communicate their state to assistive tech
  • Loading state communicated to assistive tech
  • Icon-only buttons carry an accessible name
  • Respects prefers-reduced-motion for hover animation
  • group - visually joined button groups
  • addon - buttons attached to inputs
  • close - dismiss/close control