button

Interactive control for form submission, dialogs, and user actions. The button element is the semantic choice for any clickable action that is not navigation.

When to Use

  • Submitting or resetting a form
  • Triggering JavaScript actions (opening dialogs, toggling states)
  • Any interactive element that performs an action on the current page

Do not use buttons for navigation. Use <a href="..."> for links to other pages.

Button Types

The type attribute determines the button's behavior within a form.

Type Behavior When to Use
button No default behavior JavaScript actions, dialogs, toggles
submit Submits the parent form (default in forms) Form submission
reset Resets form fields to initial values Clear form data

Code

<!-- Default button (for JS actions) --> <button type="button">Click Me</button> <!-- Form submission --> <button type="submit">Submit</button> <!-- Form reset --> <button type="reset">Reset</button>

Style Variants

Visual variants communicate hierarchy and importance.

Primary (Default)

High-emphasis actions. Use sparingly, typically once per section.

.secondary

Medium-emphasis actions. Outlined style that pairs with primary.

.ghost

Low-emphasis actions. Text-only style for tertiary actions.

Combined Example

Code

<button type="button">Primary</button> <button type="button" class="secondary">Secondary</button> <button type="button" class="ghost">Ghost</button>

Size Variants

Size variations for different contexts.

Class Padding Font Size Use Case
.small xs / s sm Compact interfaces, inline actions
(default) s / m inherit Standard actions
.large m / l lg CTAs, hero sections
.full-width (inherits) (inherits) Full-width buttons, form submit

Code

<button type="button" class="small">Small</button> <button type="button">Default</button> <button type="button" class="large">Large</button> <button type="button" class="full-width">Full Width</button>

Button States

Disabled

Use the disabled attribute to prevent interaction.

Focus State

Focus is indicated with an outline when navigating via keyboard. Tab through buttons to see the focus ring.

Code

<!-- Disabled button --> <button type="button" disabled>Cannot Click</button> <!-- Focus is automatic on keyboard navigation -->

Buttons with Icons

Buttons can include icons using the icon-wc component. The button's flexbox layout automatically handles alignment.

Code

<button type="button"> <icon-wc name="plus"></icon-wc> Add Item </button>

Button in Forms

Buttons work seamlessly within form elements. For enhanced form fields, see the form-field custom element.

Code

<form class="stacked"> <div class="group"> <label for="email">Email</label> <input type="email" id="email" /> </div> <div class="actions end"> <button type="reset" class="secondary">Reset</button> <button type="submit">Subscribe</button> </div> </form>

Accessibility Notes

  • Always include text: Buttons should have visible text. For icon-only buttons, add aria-label
  • Use native buttons: Avoid <div onclick> patterns. Native buttons are keyboard accessible
  • Visible focus: The focus ring is essential for keyboard navigation. Do not remove it
  • Disabled state: Disabled buttons are not focusable. Consider keeping buttons enabled with validation messages instead
  • Minimum touch target: Buttons have a minimum size of 44x44px for touch accessibility

Icon-Only Button

<button type="button" aria-label="Close dialog"> <icon-wc name="x"></icon-wc> </button>

CSS Reference

button, .button { display: inline-flex; align-items: center; justify-content: center; gap: var(--size-xs); padding-block: var(--size-s); padding-inline: var(--size-m); min-block-size: var(--size-touch-min); min-inline-size: var(--size-touch-min); background: var(--color-interactive); color: white; border: none; border-radius: var(--radius-m); font: inherit; font-weight: 500; cursor: pointer; transition: background var(--duration-fast) var(--ease-default); } button:hover { background: var(--color-interactive-hover); } button:focus-visible { outline: var(--border-width-medium) solid var(--color-interactive); outline-offset: var(--border-width-medium); } button:disabled { opacity: 0.5; cursor: not-allowed; } button.secondary { background: transparent; color: var(--color-interactive); border: var(--border-width-thin) solid currentColor; } button.ghost { background: transparent; color: var(--color-text); } button.small { padding-block: var(--size-xs); padding-inline: var(--size-s); font-size: var(--font-size-sm); } button.large { padding-block: var(--size-m); padding-inline: var(--size-l); font-size: var(--font-size-lg); } button.full-width { inline-size: 100%; }

Button-Styled Links

Need a link that looks like a button? Use class="button" on an <a> element. All variants and sizes apply — .secondary, .ghost, .small, .large, .full-width.

Link as Button Secondary Link

See the <a> documentation for full examples and guidelines.

Related Elements

  • a - For navigation; use class="button" for button-styled links
  • form - Container for form controls including buttons
  • input - Form inputs that buttons interact with
  • form-field - Enhanced form field wrapper