Skip to content
opsinjs
Edit this page

Components

Button

A control you press to make something happen. It is the least clinical component here, and its page sets the pattern every other component page follows.

Usage

pnpm dlx shadcn@latest add @opsinjs/button

The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.

import { Button } from "@/components/ui/button"
<Button variant="primary" onClick={save}>
  Save reading
</Button>

Examples

Theme
Density
Text
Status
Accent theme
Accent
button · base base · style base-lyraOpen under the product theme

One primary per surface

One filled button answers what should I do here? Everything else is secondary or quiet.

Theme
Density
Text
Status
Accent theme
Accent
button-one-primary-per-surface · base base · style base-lyraOpen under the product theme
button-one-primary-per-surface.tsx
import { Plus } from "lucide-react"

import { Button } from "@/components/ui/button"

export default function ButtonOnePrimaryPerSurface() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-opsin-4">
      <p className="m-0 text-opsin-body text-muted-foreground">
        Example measurement, taken this morning.
      </p>
      <div className="flex flex-wrap items-center gap-opsin-2">
        <Button variant="primary" icon={<Plus />}>
          Add a reading
        </Button>
        <Button variant="secondary">Edit this reading</Button>
        <Button variant="quiet">Cancel</Button>
      </div>
      <div className="flex flex-wrap items-center gap-opsin-2">
        <Button variant="destructive">Delete this example reading</Button>
      </div>
    </div>
  )
}

Busy, at the foot of a form

busy keeps the label, blocks activation and shows the indicator in the icon's seat. busyLabel="Saving" gives the state a word, and fullWidth stops the control growing when it appears.

Theme
Density
Text
Status
Accent theme
Accent
button-busy-at-the-foot-of-a-form · base base · style base-lyraOpen under the product theme
button-busy-at-the-foot-of-a-form.tsx
"use client"

import { ArrowRight } from "lucide-react"

import { Button } from "@/components/ui/button"

export default function ButtonBusyAtTheFootOfAForm() {
  return (
    <form
      className="flex w-full max-w-xs flex-col gap-opsin-3"
      onSubmit={(event) => event.preventDefault()}
    >
      <div className="flex flex-col gap-opsin-1">
        <label
          htmlFor="button-example-note"
          className="text-opsin-subheadline text-foreground"
        >
          Example note
        </label>
        <input
          id="button-example-note"
          name="example-note"
          type="text"
          autoComplete="off"
          aria-describedby="button-example-note-hint"
          className="min-h-(--opsin-target-minimum,2.75rem) rounded-opsin-md border border-border bg-card px-opsin-3 py-opsin-2 text-opsin-body text-foreground"
        />
        <p
          id="button-example-note-hint"
          className="m-0 text-opsin-footnote text-muted-foreground"
        >
          Anything at all. Nothing here is stored or sent.
        </p>
      </div>

      <div className="flex flex-col gap-opsin-4">
        <Button
          type="submit"
          variant="primary"
          icon={<ArrowRight />}
          iconPosition="trailing"
          busy
          busyLabel="Saving"
          fullWidth
        >
          Save note
        </Button>
        <Button type="button" variant="quiet" className="self-center">
          Cancel
        </Button>
      </div>
    </form>
  )
}

When to use it

Use it when

  • An action that changes something: saving a reading, submitting a form, confirming a decision.
  • The one primary action on a surface, with everything else secondary or quiet.

Do not use it when

  • The control takes the reader somewhere. A new URL is a link, however it is styled.Use link instead.
  • The control turns something on or off immediately, with no confirmation step.Use switch instead.
  • The control chooses one of a few options rather than performing an action.Use segmented-control instead.
  • The control is icon-only, in a toolbar or a header.Use icon-button instead.
  • The action is a clinical instruction with an author and a time behind it.Use care-card instead.

Accessibility

It is a real button with the platform role and keys, named by its visible label, with the icon aria-hidden. busy works through aria-busy and aria-disabled, so the control keeps its tab stop, and the outline focus ring never shifts layout. A press sinks it to 0.97 on pointer-down and lets it settle back on spring-snap, and a busy control does not sink. Under prefers-reduced-motion the sink is a single frame with no travel. Motion sets out all five interaction motions. Rendered, it shows no axe, target-size, focus-visible or reflow failure, and the audit changed nothing.

Residual items.

  • No live region mounts, by design. busy reaches the tree on the focused control as aria-busy plus aria-disabled, and busyLabel carries a word there, but with no busyLabel it is not otherwise announced.
  • The ring is an outline with offset, so an ancestor set to clip can hide it.
  • Button.Target raises the hit area to the 44px floor under the SC 2.5.8 inline exception, so a project without the product stylesheet owes --opsin-target-separation.
  • quiet has no fill and no boundary, so its accent ink is the cue a reader who cannot hover has that it is a control. It is never underlined; an underline marks a link inside running text.
KeyActionNotes
TabMoves focus to the buttonOne tab stop for the whole control. A busy button keeps its stop.
Shift+TabMoves focus back outNatural DOM order. A tabIndex above zero raises a development warning.
EnterActivates the buttonPlatform behaviour on a real button element. Blocked while busy.
SpaceActivates the buttonConsumed by the button, so the page does not scroll. Blocked while busy.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor

These are the measured token pairs this component draws colour from, not a measurement of the component itself.

Props interface

Prop

Type

Generated from ButtonProps in registry/bases/base/button.tsx.

type defaults to button, not submit, so a form's submit control has to say type="submit". There is no disabled convenience prop: the native attribute is the whole of it, and passing busy and disabled together warns in development. className and style merge caller last and must never resolve a --opsin-status-* or --opsin-category-* role, because a Button carries no clinical axis.

Data attributes

AttributeConditionValue
data-slotOn the root and every inner part, alwaysbutton, button-target, button-icon, button-busy, button-busy-label, button-label
data-disabledOn the root while busy or while the caller's disabled prop is truePresent with no value; absent otherwise