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
button · base base · style base-lyraOpen under the product themeOne primary per surface
One filled button answers what should I do here? Everything else is secondary or quiet.
button-one-primary-per-surface · base base · style base-lyraOpen under the product themeimport { 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.
button-busy-at-the-foot-of-a-form · base base · style base-lyraOpen under the product theme"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
linkinstead. - The control turns something on or off immediately, with no confirmation step.Use
switchinstead. - The control chooses one of a few options rather than performing an action.Use
segmented-controlinstead. - The control is icon-only, in a toolbar or a header.Use
icon-buttoninstead. - The action is a clinical instruction with an author and a time behind it.Use
care-cardinstead.
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.
busyreaches the tree on the focused control asaria-busyplusaria-disabled, andbusyLabelcarries a word there, but with nobusyLabelit is not otherwise announced. - The ring is an outline with offset, so an ancestor set to clip can hide it.
Button.Targetraises 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.quiethas 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.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus to the button | One tab stop for the whole control. A busy button keeps its stop. |
| Shift+Tab | Moves focus back out | Natural DOM order. A tabIndex above zero raises a development warning. |
| Enter | Activates the button | Platform behaviour on a real button element. Blocked while busy. |
| Space | Activates the button | Consumed by the button, so the page does not scroll. Blocked while busy. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below 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
| Attribute | Condition | Value |
|---|---|---|
| data-slot | On the root and every inner part, always | button, button-target, button-icon, button-busy, button-busy-label, button-label |
| data-disabled | On the root while busy or while the caller's disabled prop is true | Present with no value; absent otherwise |