Skip to content

Button

A button acts; a link styled as one goes somewhere.

<div class="cap-specimen-row" id="variants">
  <button type="button" class="cap-btn" id="b-default">Refresh</button>
  <button type="button" class="cap-btn" data-variant="primary" id="b-primary">Save changes</button>
  <button type="button" class="cap-btn" data-variant="secondary" id="b-secondary">Preview</button>
  <button type="button" class="cap-btn" data-variant="danger" id="b-danger">Revoke agent</button>
  <button type="button" class="cap-btn" data-variant="quiet" id="b-quiet">Show more</button>
  <button type="button" class="cap-btn" data-variant="link" id="b-variant-link">View logs</button>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/button.css";
import { morphFrom, morphLabel } from "capsomer/behavior/button";

Usage

<button type="button" class="cap-btn">Refresh</button>
<button type="button" class="cap-btn" data-variant="primary">Save changes</button>
<button type="button" class="cap-btn" data-variant="danger">Revoke agent</button>
<button type="button" class="cap-btn" data-variant="quiet">Show more</button>
<button type="button" class="cap-btn" data-variant="secondary" data-size="sm">Preview</button>
<button type="button" class="cap-btn" data-variant="link">View logs</button>
<button type="button" class="cap-btn"><svg data-icon="start" aria-hidden="true">...</svg>Add a site</button>
<div class="cap-btn-group" role="group" aria-label="Page navigation">
  <button type="button" class="cap-btn">Previous</button>
  <button type="button" class="cap-btn">Next</button>
</div>
<button type="button" class="cap-btn" data-icon-only aria-label="Refresh sites"><svg aria-hidden="true">...</svg></button>

<button type="button" class="cap-btn" aria-disabled="true" aria-describedby="why">Publish</button>
<span class="cap-btn-reason" id="why">Fix the 2 problems above first.</span>

<button type="button" class="cap-btn" aria-busy="true">
  <span class="cap-btn-spinner" aria-hidden="true"></span><span class="cap-btn-label">Save changes</span>
</button>

<a class="cap-btn" href="/queue">Open the queue</a>
<button type="button" class="cap-link-btn">Undo</button>
<Button variant="primary" pending={saving} onClick={save}>Save changes</Button>
<Button disabledReason="Fix the 2 problems above first.">Publish</Button>
<Button iconOnly label="Refresh sites"><RefreshIcon /></Button>
<Button morph variant="primary" onClick={save}>{saved ? "Saved" : saving ? "Saving…" : "Save draft"}</Button>

Examples

Sizes

<div class="cap-specimen-row">
  <button type="button" class="cap-btn" data-size="xs" id="b-xs">Extra small</button>
  <button type="button" class="cap-btn" data-size="sm" id="b-sm">Small</button>
  <button type="button" class="cap-btn" id="b-size-default">Default</button>
  <button type="button" class="cap-btn" data-size="lg" id="b-lg">Large</button>
</div>
<div class="cap-specimen-row">
  <button type="button" class="cap-btn" data-icon-only data-size="xs" aria-label="Add a site, extra small">
    <svg width="12" height="12" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" d="M8 3v10M3 8h10" /></svg>
  </button>
  <button type="button" class="cap-btn" data-icon-only data-size="sm" aria-label="Add a site, small">
    <svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" d="M8 3v10M3 8h10" /></svg>
  </button>
  <button type="button" class="cap-btn" data-icon-only aria-label="Add a site">
    <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" d="M8 3v10M3 8h10" /></svg>
  </button>
  <button type="button" class="cap-btn" data-icon-only data-size="lg" aria-label="Add a site, large">
    <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" d="M8 3v10M3 8h10" /></svg>
  </button>
</div>

Hover

<div class="cap-specimen-row">
  <button type="button" class="cap-btn" id="b-hover">Refresh</button>
  <button type="button" class="cap-btn" data-variant="primary">Save changes</button>
  <button type="button" class="cap-btn" data-variant="secondary" id="b-secondary-hover">Preview</button>
  <button type="button" class="cap-btn" data-variant="danger">Revoke agent</button>
  <button type="button" class="cap-btn" data-variant="quiet" id="b-quiet-hover">Show more</button>
  <button type="button" class="cap-btn" data-variant="link">View logs</button>
  <button type="button" class="cap-btn" id="b-sweep-hover" style="--btn-sweep: 1">See it live (a site's sweep)</button>
</div>

Keyboard focus

<p class="cap-muted">Press Tab to reach a button: the ring is 3 px in the accent.</p>
<div class="cap-specimen-row">
  <button type="button" class="cap-btn" id="b-focus">Refresh</button>
  <button type="button" class="cap-btn" data-variant="primary">Save changes</button>
</div>

Pressed, and open

<div class="cap-specimen-row">
  <button type="button" class="cap-btn" id="b-pressed">Refresh</button>
  <button type="button" class="cap-btn" data-variant="primary">Save changes</button>
  <button type="button" class="cap-btn" data-variant="secondary">Preview</button>
  <button type="button" class="cap-btn" data-variant="danger" id="b-danger-pressed">Revoke agent</button>
  <button type="button" class="cap-btn" aria-haspopup="menu" aria-expanded="true" id="b-expanded">Sort by</button>
</div>

Disabled, with its reason

<div class="cap-specimen-row">
  <button type="button" class="cap-btn" aria-disabled="true" aria-describedby="why-publish" id="b-disabled">Publish</button>
  <span class="cap-btn-reason" id="why-publish">Fix the 2 problems above first.</span>
</div>
<div class="cap-specimen-row">
  <button type="button" class="cap-btn" data-variant="primary" aria-disabled="true" aria-describedby="why-deploy">Deploy</button>
  <span class="cap-btn-reason" id="why-deploy">A deploy is already running for example.com.</span>
</div>
<div class="cap-specimen-row">
  <button type="button" class="cap-btn" data-variant="secondary" aria-disabled="true" aria-label="Preview, unavailable">Preview</button>
  <button type="button" class="cap-btn" data-variant="quiet" aria-disabled="true" aria-label="Show more, unavailable">Show more</button>
  <button type="button" class="cap-btn" data-variant="link" aria-disabled="true" aria-label="View logs, unavailable">View logs</button>
</div>

Invalid

<div class="cap-specimen-row">
  <button type="button" class="cap-btn" aria-invalid="true" id="b-invalid">Submit form</button>
</div>

Pending

<div class="cap-specimen-row">
  <button type="button" class="cap-btn" aria-busy="true" id="b-pending"><span class="cap-btn-spinner" aria-hidden="true"></span><span class="cap-btn-label">Refresh</span></button>
  <button type="button" class="cap-btn" data-variant="primary" aria-busy="true"><span class="cap-btn-spinner" aria-hidden="true"></span><span class="cap-btn-label">Save changes</span></button>
  <button type="button" class="cap-btn" id="b-pending-twin"><span class="cap-btn-spinner" aria-hidden="true"></span><span class="cap-btn-label">Refresh</span></button>
</div>
<p class="cap-muted">The last button is the same one at rest: a pending button keeps its width.</p>

A label that changes

<div class="cap-specimen-row">
  <button type="button" class="cap-btn" data-variant="primary" id="b-morph"><span class="cap-btn-label">Save draft</span></button>
</div>
<p class="cap-muted">Press it: Save draft, Saving…, Saved. The width eases and the words crossfade.</p>

Icons

<div class="cap-specimen-row">
  <button type="button" class="cap-btn" data-icon-only aria-label="Refresh sites" id="b-icon">
    <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" d="M13 8a5 5 0 1 1-1.5-3.6M13 2.5V5h-2.5" /></svg>
  </button>
  <button type="button" class="cap-btn" data-icon-only data-variant="quiet" aria-label="More actions for example.com">
    <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" d="M3 7h2v2H3zM7 7h2v2H7zM11 7h2v2h-2z" /></svg>
  </button>
  <button type="button" class="cap-btn">
    <svg data-icon="start" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" d="M8 3v10M3 8h10" /></svg>
    Add a site
  </button>
  <button type="button" class="cap-btn" data-variant="primary">
    Next
    <svg data-icon="end" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" d="M6 3l5 5-5 5" /></svg>
  </button>
</div>
<div class="cap-specimen-row">
  <a class="cap-btn" href="#jobs" id="b-link">Open the queue</a>
  <a class="cap-btn" data-variant="primary" href="#jobs">Write a post</a>
  <span>Pushed to capsomer-driver. <button type="button" class="cap-link-btn" id="b-linkbtn">Undo</button></span>
  <button type="button" class="cap-link-btn">Clear filter</button>
</div>
<p id="jobs" class="cap-muted">The queue would open here.</p>

Button group

<div class="cap-specimen-row">
  <div class="cap-btn-group" role="group" aria-label="Page navigation" id="b-group">
    <button type="button" class="cap-btn">Previous</button>
    <button type="button" class="cap-btn">Next</button>
  </div>
  <div class="cap-btn-group" role="group" aria-label="Post actions">
    <span class="cap-btn-group-text">12 drafts</span>
    <button type="button" class="cap-btn">Archive</button>
    <button type="button" class="cap-btn">Snooze</button>
  </div>
  <div class="cap-btn-group" role="group" aria-label="Sort" data-orientation="vertical">
    <button type="button" class="cap-btn">Newest</button>
    <button type="button" class="cap-btn">Oldest</button>
  </div>
</div>

Comfortable density

<div class="cap-specimen-row" data-density="comfortable" id="b-comfortable">
  <button type="button" class="cap-btn">Refresh</button>
  <button type="button" class="cap-btn" data-variant="primary">Save changes</button>
  <button type="button" class="cap-btn" data-variant="secondary">Preview</button>
  <button type="button" class="cap-btn" data-variant="quiet">Show more</button>
  <button type="button" class="cap-btn" data-size="xs">Extra small</button>
  <button type="button" class="cap-btn" data-size="lg">Large</button>
</div>

API reference

Button

PropTypeRequiredDoes
pendingbooleanIn flight: the label stays (so the width and the name stay) and a spinner covers it. Clicks are ignored until it settles.
pendingLabelstringSaid once to a screen reader when pending turns on ("Connecting to Stripe"), from a polite live region beside the button that is always in the page, so the change is heard.
wrapbooleanA long label wraps onto more lines (a narrow column, a phone).
blockbooleanFills its row.
disabledReasonReactNodeDisabled, with the reason written beside the button. The button stays focusable and the reason is its description; clicks are ignored.
iconOnlybooleanAn icon button: children is the icon and label its accessible name.
labelstring
morphbooleanA label that changes in place (Save, Saving…, Saved) eases the width and crossfades the words. The label is wrapped in .cap-btn-label.
refRef<HTMLButtonElement>The button element, for an app that moves focus to it (React 19 passes it through).
childrenReactNode
variant"default" | "primary" | "secondary" | "danger" | "quiet" | "link"
size"xs" | "sm" | "default" | "lg"

And every attribute of <button>.

ButtonGroup

PropTypeRequiredDoes
labelstring
orientation"horizontal" | "vertical"
childrenReactNode
classNamestring

ButtonGroupText

PropTypeRequiredDoes
childrenReactNode

Functions

FunctionSignatureDoes
morphFrom(button: HTMLElement, from: number, old: HTMLElement): numberAnimates a label that has already changed, from the button's width before the change and a copy of the old label. The React wrapper calls it after React has written the new label. Widths are layout widths (offsetWidth), so a pressed button's scale does not count. Returns the new label's width.
morphLabel(button: HTMLElement, change: () => void): voidChanges a button's label with the morph: change writes the new label (into .cap-btn-label), e.g. morphLabel(save, () => (label.textContent = "Saving…")).

CSS variables

VariableDefault
--cap-btn-bgvar(--raised)
--cap-btn-fgvar(--text)
--cap-btn-fsvar(--fs-body)
--cap-btn-gapvar(--space-2-5)
--cap-btn-hvar(--control)
--cap-btn-hovercolor-mix(in srgb, var(--raised), var(--text) 7%)
--cap-btn-icon16px
--cap-btn-linevar(--line-strong)
--cap-btn-presscolor-mix(in srgb, var(--raised), var(--text) 12%)

Parts and data attributes

ClassIs
.cap-btnthe root
.cap-btn-awaya part
.cap-btn-groupa part
.cap-btn-group-texta part
.cap-btn-labela part
.cap-btn-reasona part
.cap-btn-spinnera part
.cap-link-btnits own class
AttributeValues
data-blockpresent or absent
data-iconend start
data-icon-onlypresent or absent
data-leavingpresent or absent
data-orientationvertical
data-sizelg sm xs
data-variantdanger default link primary quiet secondary
data-wrappresent or absent
StateRead from
:activethe platform
:disabledthe platform
:focus-visiblethe platform
:hoverthe platform
[aria-busy="true"]an attribute
[aria-disabled="true"]an attribute
[aria-expanded="true"]an attribute
[aria-haspopup]an attribute
[aria-invalid="true"]an attribute

Accessibility

KeyDoes
TabMoves to the next button, including one disabled with its reason
Enter or SpaceActivates a button
EnterFollows a link styled as a button (Space does not, as for any link)
  • Every icon button has an accessible name; show a word as well wherever there is room.
  • A disabled button's reason is its accessible description.
  • In plain HTML, aria-disabled and aria-busy do not stop a click: the handler returns early when either is "true", and the button is type="button" unless it submits. The React Button does this for you.
  • Forced colors: a disabled button and link button turn GrayText; a quiet button gains its border.