Button

Actions with solid, outline or text styles.

When to use

Use a button to perform an action such as saving a form or opening a dialog. Use a link with an href to navigate, even when it is styled as a button.

Variants

Combine .btn with one style and semantic color. The preview shows solid, outline and text styles, plus a labelled icon button.

HTML
<button type="button" class="btn btn-solid btn-primary">Solid</button>
<button type="button" class="btn btn-outline btn-secondary">Outline</button>
<button type="button" class="btn btn-text btn-primary">Text</button>

Sizes and states

Use .btn-xs, .btn-sm or .btn-lg for sizing. The default size needs no additional class. Use native disabled to disable a button; .is-active applies active styling.

Disabled colors take precedence over active styling. Controls that remain keyboard-focusable retain their visible focus ring. A temporarily disabled toggle can retain .is-active and aria-pressed; its active appearance returns when it is enabled again.

HTML
<button type="button" class="btn btn-solid btn-primary btn-sm">Small</button>
<button type="button" class="btn btn-solid btn-primary is-active">Active</button>
<button type="button" class="btn btn-solid btn-primary" disabled>Disabled</button>

Accessibility and behavior

  • Use native <button> elements for actions. Set type="button" unless the button should submit a form; use type="submit" for submission.
  • Keep a visible, descriptive label when adding an icon. For an icon without visible text, use the Icon button pattern with an accessible name.
  • Native buttons support Enter and Space. Keep their visible focus indicator when customizing styles.
  • .is-active changes appearance only. For a toggle action, also expose its state with aria-pressed="true" or aria-pressed="false" and update it when the action runs.
  • Use the native disabled attribute for unavailable actions. The .disabled class alone does not disable keyboard activation or communicate the disabled state.

CSS variables

--action-color* controls primary text and outlines; --primary* controls solid surfaces.

Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.

TokenDefaultPurposeScope / state
--button-colorvar(--text-color)Text and border color for outline and text variants..btn-outline / .btn-text
--button-color-hovervar(--text-color)Text color on hover for text buttons..btn-outline / .btn-text
--button-color-activevar(--text-color)Text color when pressed or marked active for text buttons..btn-outline / .btn-text
--button-on-colorvar(--on-primary)Text and icon color on filled surfaces..btn-solid / .btn-outline
--button-surface-colorvar(--button-color)Background and border color for solid buttons..btn-solid / .btn-outline
--button-surface-color-hovervar(--button-color-hover)Filled background and border color on hover..btn-solid / .btn-outline
--button-surface-color-activevar(--button-color-active)Filled background and border color when pressed or marked active..btn-solid / .btn-outline
--button-border-widthvar(--border-width)Border thickness..btn
--button-border-radiusvar(--border-radius)Corner radius..btn
--button-focus-outline-widthvar(--focus-outline-width)Focus ring thickness..btn (focus)
--button-focus-outline-stylevar(--focus-outline-style)Focus ring line style..btn (focus)
--button-focus-outline-colorvar(--focus-outline-color)Focus ring color..btn (focus)
--button-focus-outline-offsetvar(--focus-offset)Distance between the focus ring and control..btn (focus)
--button-font-sizevar(--font-size)Text size..btn
--button-padding-yvar(--spacer-1)Top and bottom padding..btn
--button-padding-xvar(--spacer-3)Left and right padding..btn
--button-disabled-text-colorvar(--disabled-text-color)Text color while disabled..btn (disabled)
--button-disabled-bg-colorvar(--disabled-bg-color)Background color while disabled..btn (disabled)
--button-disabled-border-colorvar(--disabled-border-color)Border color while disabled..btn (disabled)
--button-transition-durationvar(--transition-duration, 0.2s)Duration of visual state transitions..btn
--button-transition-easingvar(--transition-easing)Timing curve for visual state transitions..btn
--button-highlightvar(--bg-highlight)Subtle background on hover or active text buttons..btn-text: hover / active

For example, customize a single button with an additional class:

CSS
.btn.project-action {
	--button-border-radius: 9999px;
	--button-padding-x: var(--spacer-4);
}