# Button

> Triggers an action. One primary button per view marks the action that matters most.

Category: Actions · Atomic level: atom · Built on Base UI Button
Page: https://ui.dtheo.dev/docs/components/button

## Install

```bash
npx dtheo@latest add button
# or, with the shadcn CLI
npx shadcn@latest add https://ui.dtheo.dev/r/button.json
```

Dependencies: @base-ui/react, clsx, tailwind-merge, class-variance-authority. Registry dependencies: utils.

## Exports

`Button`, `buttonVariants`

## Use it for

- Submitting, saving, running, creating
- Icon-only toolbar actions (with an aria-label)
- Links that look like buttons, via `render={<a />}`

## Reach for something else

- Navigation in running text: use a link
- Toggling a persistent state: use Toggle or Switch

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'link'` | `'secondary'` | Visual weight. Use primary once per view. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | `'md'` | Control height: 22, 24, 28 (36 on touch), 32px. |
| `loading` | `boolean` | `false` | Shows a spinner, keeps the width, sets aria-busy. |
| `render` | `ReactElement` | – | Render as another element, e.g. a link, keeping the styles and behavior. |

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Activates the button |
| Tab | Moves focus to the next control |

## Accessibility

- Icon-only buttons need an `aria-label` that names the action ("Delete run"), not the icon.
- `loading` keeps the button focusable and sets `aria-busy`, so focus is not lost mid-action.
- Disabled buttons are skipped by Tab; prefer explaining why an action is unavailable.

## Examples

### button-variants

```tsx
import { PlayIcon, Trash2Icon, DownloadIcon, MoreHorizontalIcon } from 'lucide-react';
import { Button } from '@/components/ui/button';

export default function ButtonVariants() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <Button variant="primary">
        <PlayIcon aria-hidden="true" />
        Run step test
      </Button>
      <Button>
        <DownloadIcon aria-hidden="true" />
        Export CSV
      </Button>
      <Button variant="outline">Compare runs</Button>
      <Button variant="ghost">Cancel</Button>
      <Button variant="destructive">
        <Trash2Icon aria-hidden="true" />
        Delete run
      </Button>
      <Button variant="ghost" size="icon" aria-label="More actions">
        <MoreHorizontalIcon aria-hidden="true" />
      </Button>
      <Button variant="link">View limits</Button>
    </div>
  );
}
```

### button-sizes

```tsx
import { MoreHorizontalIcon, RotateCcwIcon } from 'lucide-react';
import { Button } from '@/components/ui/button';

const sizes = [
  { size: 'xs', icon: 'icon-xs', height: '22 px', use: 'Table rows' },
  { size: 'sm', icon: 'icon-sm', height: '24 px', use: 'Toolbars' },
  { size: 'md', icon: 'icon', height: '28 px', use: 'Default, 36 px on touch' },
  { size: 'lg', icon: 'icon-lg', height: '32 px', use: 'Page actions' },
] as const;

export default function ButtonSizes() {
  return (
    <div className="grid grid-cols-2 gap-x-8 gap-y-6 sm:grid-cols-4">
      {sizes.map(({ size, icon, height, use }) => (
        <div key={size} className="flex flex-col items-center gap-2 text-center">
          <div className="flex min-h-control-touch items-center gap-1">
            <Button size={size}>
              <RotateCcwIcon aria-hidden="true" />
              Rerun
            </Button>
            <Button variant="ghost" size={icon} aria-label="More actions for R-0412">
              <MoreHorizontalIcon aria-hidden="true" />
            </Button>
          </div>
          <div className="flex flex-col">
            <span className="text-label text-foreground tabular-nums">
              {size} · {height}
            </span>
            <span className="text-caption text-muted-foreground">{use}</span>
          </div>
        </div>
      ))}
    </div>
  );
}
```

### button-loading

```tsx
import * as React from 'react';
import { PlayIcon } from 'lucide-react';
import { Button } from '@/components/ui/button';

const runId = (n: number) => `R-${String(n).padStart(4, '0')}`;

export default function ButtonLoading() {
  const [loading, setLoading] = React.useState(false);
  const [lastRun, setLastRun] = React.useState<number | null>(null);
  const timer = React.useRef<ReturnType<typeof setTimeout>>(undefined);
  React.useEffect(() => () => clearTimeout(timer.current), []);

  const queue = () => {
    setLoading(true);
    timer.current = setTimeout(() => {
      setLoading(false);
      setLastRun((n) => (n ?? 412) + 1);
    }, 1500);
  };

  return (
    <div className="flex flex-col items-center gap-3">
      {/* While loading, the label stays in place (invisible) so the button keeps its width. */}
      <Button variant="primary" loading={loading} onClick={queue}>
        <PlayIcon aria-hidden="true" />
        Queue retune run
      </Button>
      <p role="status" className="text-caption text-muted-foreground tabular-nums">
        {loading
          ? 'Reserving Bench 3…'
          : lastRun
            ? `${runId(lastRun)} queued on Bench 3 with Kp 3.60, Kd 0.09.`
            : 'Reruns the R-0412 step with Kp 3.60, Kd 0.09.'}
      </p>
    </div>
  );
}
```

## Used in

- Run review (page): https://ui.dtheo.dev/examples/run-review
- Motor map (page): https://ui.dtheo.dev/examples/motor-map
- Loop tuning (page): https://ui.dtheo.dev/examples/tuning
- Lab assistant (page): https://ui.dtheo.dev/examples/assistant
- Home page (page): https://ui.dtheo.dev/
- Data table pattern (template): https://ui.dtheo.dev/docs/patterns/data-table
- Forms pattern (template): https://ui.dtheo.dev/docs/patterns/forms
- States pattern (template): https://ui.dtheo.dev/docs/patterns/states
- Dialog (organism): https://ui.dtheo.dev/docs/components/dialog
- Alert dialog (organism): https://ui.dtheo.dev/docs/components/alert-dialog
- App shell (template): https://ui.dtheo.dev/docs/components/app-shell
