# Button

> Triggers an action. Five hierarchies, five sizes from 24 to 56px.

URL: https://docs.atomus.io/components/button/

Triggers an action. Five hierarchies, five sizes from 24 to 56px.

Add the source to a shadcn project

`npx shadcn@latest add https://docs.atomus.io/r/button.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fbutton.json)

Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/)

## In Figma

From `guidelines/components/button.md` · Open in Figma: [Button](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25416-2898)

Properties, variants and anatomy of the Figma components. React props use the same names.

### Button

Hierarchy: Primary (main action, one per view), Secondary, Outline, Tertiary (low emphasis), Link. Sizes xs–xl (24–56px). Icons via instance swap. Loading shows a spinner.

Variants: 125

| Property           | Type / options                                  |
| ------------------ | ----------------------------------------------- |
| Label              | text                                            |
| Leading icon       | boolean (off)                                   |
| Leading icon swap  | instance swap (icon)                            |
| Trailing icon      | boolean (off)                                   |
| Trailing icon swap | instance swap (icon)                            |
| Hierarchy          | Primary · Secondary · Outline · Tertiary · Link |
| Size               | xs · sm · md · lg · xl                          |
| State              | Default · Hover · Focused · Disabled · Loading  |

### Button icon

Icon-only button. Same hierarchies, sizes and states as Button; square 24–56px. Always give it a tooltip or aria-label in code.

Variants: 100

| Property  | Type / options                                 |
| --------- | ---------------------------------------------- |
| Icon      | instance swap (icon)                           |
| Hierarchy | Primary · Secondary · Outline · Tertiary       |
| Size      | xs · sm · md · lg · xl                         |
| State     | Default · Hover · Focused · Disabled · Loading |

## Usage

```tsx
import { Button } from '@stanvision/atomus-react';

<Button hierarchy="primary" size="md" iconLeading={<PlusIcon />}>
  New project
</Button>
```

Triggers an action. One **primary** per view for the main action; **secondary** or **outline** for the rest; **tertiary** in toolbars and dense rows; **link** for inline, low-emphasis actions.

### Props at a glance

Full types and defaults are in [React API](#react-api) at the end of the page.

- `children` — the label: a verb in sentence case (“Save changes”).
- `hierarchy` — `primary` · `secondary` · `outline` · `tertiary` · `link` (Figma: Hierarchy; default `secondary`).
- `size` — `xs` 24 · `sm` 32 · `md` 40 · `lg` 48 · `xl` 56 (Figma: Size). Match the inputs on the same row.
- `iconLeading` / `iconTrailing` — an icon element (Figma: Leading/Trailing icon swap). `iconOnly` + `aria-label` for icon buttons.
- `loading` — spinner, disabled while busy (Figma: State=Loading).

**Do**

- Use `lg`/`xl` on marketing pages, `md` in product UI, `sm`/`xs` in tables and toolbars.

### Design guidance

From the Figma guidelines.

#### Button

**Do**

- Use one primary button per view, for the main action.
- Label with a verb in sentence case: “Save changes”, not “OK”.
- Match sizes in a row — buttons and inputs share the 32 / 40 / 48 heights.
- Put the primary action last in a group, after Cancel.

**Forbidden**

- Never put two primary buttons in one view.
- Never use the Link style for destructive actions.
- Never detach to change an icon — use Leading / Trailing icon swap.
- Never use a button to navigate to another page — use a link.

#### Button icon

**Do**

- Always give it an accessible name (`aria-label`) and a tooltip.
- Use Tertiary in toolbars, cards and table rows.

**Forbidden**

- Never use an icon-only button for the main action of a view.
- Never use an icon whose meaning is not widely understood without a label.

## React API

Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/button.md`.

Use only these props; anything else is not part of the API.

### `Button`

`import { Button } from '@stanvision/atomus-react';` — source: `react/src/components/Button.tsx`

| Prop           | Type                                                            | Default       | Description                                                        |
| -------------- | --------------------------------------------------------------- | ------------- | ------------------------------------------------------------------ |
| `hierarchy`    | `'primary' \| 'secondary' \| 'outline' \| 'tertiary' \| 'link'` | `'secondary'` | Figma: Hierarchy                                                   |
| `size`         | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                          | `'md'`        | Figma: Size — xs 24 · sm 32 · md 40 · lg 48 · xl 56                |
| `iconLeading`  | `ReactNode`                                                     | —             | Figma: Leading icon + Leading icon swap                            |
| `iconTrailing` | `ReactNode`                                                     | —             | Figma: Trailing icon + Trailing icon swap                          |
| `loading`      | `boolean`                                                       | —             | Figma: State=Loading                                               |
| `iconOnly`     | `boolean`                                                       | —             | Square icon-only button (Figma: Button icon). Requires aria-label. |
| `fullWidth`    | `boolean`                                                       | —             | Stretches to the width of its container.                           |

Also accepts every native `<button>` attribute (`onClick`, `type`, `disabled`, `form` …), and `ref` (forwarded to the `<button>`).

---
All Atomus docs for agents: https://docs.atomus.io/llms.txt