---
title: "Button"
description: "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."
url: "https://opsinjs.pensievelabs.org/docs/components/button"
source: "https://opsinjs.pensievelabs.org/docs/components/button.md"
section: "Components"
status: "shipped"
kind: "component"
category: "actions-and-forms"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["cta", "action", "submit", "primary button"]
usedIn: ["daily-logging", "forms", "onboarding-and-first-run"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="button"
  status="shipped"
  questions="[
  &#x22;Whether an ink outline is warning enough for the destructive variant, or whether a destructive action belongs behind a confirmation Dialog instead.&#x22;,
  &#x22;A busy button given no busyLabel leaves a reduced-motion reader a still glyph and no word for what is happening.&#x22;,
  &#x22;Base UI defaults type to button, so a form's submit control has to say type=\&#x22;submit\&#x22;; whether to restore the platform default is open.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="button" unbuilt="false" importPath="@/components/ui/button" dependencies="[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]" />

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

```tsx
<Button variant="primary" onClick={save}>
  Save reading
</Button>
```

## Examples [#examples]

<ComponentPreview name="button" />

### One primary per surface [#one-primary-per-surface]

One filled button answers &#x2A;what should I do here?* Everything else is secondary or
quiet.

<ComponentPreview name="button-one-primary-per-surface" kind="example" align="start" />

### Busy, at the foot of a form [#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.

<ComponentPreview name="button-busy-at-the-foot-of-a-form" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;An action that changes something: saving a reading, submitting a form, confirming a decision.&#x22;,
  &#x22;The one primary action on a surface, with everything else secondary or quiet.&#x22;,
]"
  avoid="[
  { case: &#x22;The control takes the reader somewhere. A new URL is a link, however it is styled.&#x22;, instead: &#x22;link&#x22; },
  { case: &#x22;The control turns something on or off immediately, with no confirmation step.&#x22;, instead: &#x22;switch&#x22; },
  { case: &#x22;The control chooses one of a few options rather than performing an action.&#x22;, instead: &#x22;segmented-control&#x22; },
  { case: &#x22;The control is icon-only, in a toolbar or a header.&#x22;, instead: &#x22;icon-button&#x22; },
  { case: &#x22;The action is a clinical instruction with an author and a time behind it.&#x22;, instead: &#x22;care-card&#x22; },
]"
/>

## Accessibility [#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](../foundations/motion.mdx) 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.

<KeyboardTable
  name="button"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus to the button&#x22;,
    notes: &#x22;One tab stop for the whole control. A busy button keeps its stop.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves focus back out&#x22;,
    notes: &#x22;Natural DOM order. A tabIndex above zero raises a development warning.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Activates the button&#x22;,
    notes: &#x22;Platform behaviour on a real button element. Blocked while busy.&#x22;,
  },
  {
    keys: &#x22;Space&#x22;,
    action: &#x22;Activates the button&#x22;,
    notes: &#x22;Consumed by the button, so the page does not scroll. Blocked while busy.&#x22;,
  },
]"
/>

<ContrastReport component="button" />

## Props interface [#props-interface]

<PropsTable name="ButtonProps" />

`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 [#data-attributes]

<DataAttributesTable
  name="button"
  rows="[
  {
    attribute: &#x22;data-slot&#x22;,
    condition: &#x22;On the root and every inner part, always&#x22;,
    value: &#x22;button, button-target, button-icon, button-busy, button-busy-label, button-label&#x22;,
  },
  {
    attribute: &#x22;data-disabled&#x22;,
    condition: &#x22;On the root while busy or while the caller's disabled prop is true&#x22;,
    value: &#x22;Present with no value; absent otherwise&#x22;,
  },
]"
/>
