# Button

Button starts an action or opens a link while keeping size, tone, loading, and disabled behavior consistent.

Use Button for an action or link treatment. Select product and marketing contexts deliberately: product for interface actions, marketing for conversion CTAs. Use `fullWidth` when a button or full-width link must fill a bounded container. Open destructive confirmation with a quiet danger action.

<h2 id="purpose">Purpose</h2>

Use Button for a clear action. Choose one primary action in a local group. Use concise, verb-led labels such as “Save changes” or “Create project”. Use its link behavior when the same visual treatment must navigate to another location.

<h2 id="anatomy">Anatomy</h2>

The component owns the interactive element, label, optional icon snippets, and loading indicator. The `children` snippet supplies the visible label. Native buttons keep their built-in keyboard behavior, while `href` renders a link for navigation. Icon-only Buttons require an accessible label. If completion matters, announce the result separately because `loading` only marks the action as busy.

<h2 id="context">Context</h2>

<h3 id="product-context">Product context</h3>

Product is the default context. It uses the semantic Button radius and the small primary shadow. Use it in forms, dialogs, settings, toolbars, tables, empty states, and onboarding flows.

<h3 id="marketing-context">Marketing context</h3>

Marketing is an explicit context. It defaults to the pill shape. An enabled primary marketing Button uses the accent glow. Use it for landing-page heroes, pricing sections, compact marketing headers, and promotional banners. Do not use it for routine product actions.

```svelte
<Button context="marketing">Get started</Button>
```

<h2 id="shape">Shape</h2>

Shape remains independent from context. `rounded` uses the default Button radius. `pill` uses the full pill radius. `circle` is for icon-only Buttons. An explicit shape overrides the context default.

<h2 id="form-alignment">Form alignment</h2>

Product Button and Input use paired semantic radii. Their heights come from separate control and field recipes, so a preset can tune each role. Use the product default when Button sits beside or below an Input in a form.

Use `sm` only when the surrounding layout provides a clear and usable target. Icon-only Buttons require an accessible label.

<h2 id="standalone-hero-cta">Standalone hero CTA</h2>

One standalone hero CTA can use `lg` when one action dominates the page. Center the CTA in the hero. Do not place a second `lg` Button beside it.

```svelte
<Button context="marketing" size="lg">Start a project</Button>
```

<h2 id="two-button-hero-cta">Two-button hero CTA</h2>

A two-button hero group uses `md` for both buttons. Variant and glow create the hierarchy. Size does not create hierarchy inside the group.

```svelte
<Button context="marketing">Get started</Button>
<Button context="marketing" variant="outline">View examples</Button>
```

<h2 id="tokens">Tokens and style hooks</h2>

Button reads semantic accent, text, focus, radius, spacing, and motion variables. Override those values through `Provider` rather than targeting internal classes.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Omit<HTMLButtonAttributes, 'children' | 'onclick'>` — Props from this native base are accepted except the listed members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `context` | `ButtonContext` | prop | No | `'product'` | No additional description. |
| `fullWidth` | `boolean` | prop | No | `false` | No additional description. |
| `href` | `string` | prop | No | `undefined` | Render an `<a>` instead of a `<button>`. |
| `icon` | `IconGlyph` | prop | No | `undefined` | Leading glyph component. |
| `iconContent` | `Snippet` | snippet | No | `undefined` | Arbitrary leading content. Takes precedence over `icon`. A glyph and a snippet are both functions at runtime, so they cannot share one prop. |
| `iconOnly` | `boolean` | prop | No | `false` | No additional description. |
| `loading` | `boolean` | prop | No | `false` | No additional description. |
| `onclick` | `(event: MouseEvent) => void` | callback | No | `undefined` | No additional description. |
| `shape` | `ButtonShape` | prop | No | `undefined` | No additional description. |
| `size` | `ButtonSize` | prop | No | `'md'` | No additional description. |
| `tone` | `ButtonTone` | prop | No | `'neutral'` | No additional description. |
| `trailing` | `IconGlyph` | prop | No | `undefined` | Trailing glyph component. |
| `trailingContent` | `Snippet` | snippet | No | `undefined` | Arbitrary trailing content. Takes precedence over `trailing`. |
| `variant` | `ButtonVariant` | prop | No | `'primary'` | No additional description. |

## Related

- [Chip](/docs/components/chip): Bindable toggle pill for compact filters on the shared control ladder.
- [CopyButton](/docs/components/copy-button): Clipboard action with temporary copied feedback.
- [Toolbar](/docs/components/toolbar): Data-driven toolbar with roving focus, action presentations and tones, and toggle groups.