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.
<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.
<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. Settype="button"unless the button should submit a form; usetype="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-activechanges appearance only. For a toggle action, also expose its state witharia-pressed="true"oraria-pressed="false"and update it when the action runs.- Use the native
disabledattribute for unavailable actions. The.disabledclass 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.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--button-color | var(--text-color) | Text and border color for outline and text variants. | .btn-outline / .btn-text |
--button-color-hover | var(--text-color) | Text color on hover for text buttons. | .btn-outline / .btn-text |
--button-color-active | var(--text-color) | Text color when pressed or marked active for text buttons. | .btn-outline / .btn-text |
--button-on-color | var(--on-primary) | Text and icon color on filled surfaces. | .btn-solid / .btn-outline |
--button-surface-color | var(--button-color) | Background and border color for solid buttons. | .btn-solid / .btn-outline |
--button-surface-color-hover | var(--button-color-hover) | Filled background and border color on hover. | .btn-solid / .btn-outline |
--button-surface-color-active | var(--button-color-active) | Filled background and border color when pressed or marked active. | .btn-solid / .btn-outline |
--button-border-width | var(--border-width) | Border thickness. | .btn |
--button-border-radius | var(--border-radius) | Corner radius. | .btn |
--button-focus-outline-width | var(--focus-outline-width) | Focus ring thickness. | .btn (focus) |
--button-focus-outline-style | var(--focus-outline-style) | Focus ring line style. | .btn (focus) |
--button-focus-outline-color | var(--focus-outline-color) | Focus ring color. | .btn (focus) |
--button-focus-outline-offset | var(--focus-offset) | Distance between the focus ring and control. | .btn (focus) |
--button-font-size | var(--font-size) | Text size. | .btn |
--button-padding-y | var(--spacer-1) | Top and bottom padding. | .btn |
--button-padding-x | var(--spacer-3) | Left and right padding. | .btn |
--button-disabled-text-color | var(--disabled-text-color) | Text color while disabled. | .btn (disabled) |
--button-disabled-bg-color | var(--disabled-bg-color) | Background color while disabled. | .btn (disabled) |
--button-disabled-border-color | var(--disabled-border-color) | Border color while disabled. | .btn (disabled) |
--button-transition-duration | var(--transition-duration, 0.2s) | Duration of visual state transitions. | .btn |
--button-transition-easing | var(--transition-easing) | Timing curve for visual state transitions. | .btn |
--button-highlight | var(--bg-highlight) | Subtle background on hover or active text buttons. | .btn-text: hover / active |
For example, customize a single button with an additional class:
.btn.project-action {
--button-border-radius: 9999px;
--button-padding-x: var(--spacer-4);
}