# Button

A clickable action. `color`, `variant` and `size` are independent axes, with `shape` and `fullWidth` as modifiers.

## Use for

- an action that finishes at once, such as Cancel or opening a dialog
- an action that waits on async work, such as a form submit or a confirm, with `SubmitButton`
- an icon-only action

## Practices

- Do: Use `SubmitButton` for any action that waits on async work. In a form it submits; outside one, pass `type='button'` and `onClick`, as `Confirmation` does.
- Do: Use `Button` for actions that finish at once, such as Cancel, Back or opening a dialog.
- Do: In a view, hold the primary action pending until the next step renders. The rules are in the Views guide (`mosaic guides inspect views`).
- Do: Use `ProviderButton` to sign in with a third-party provider.
- Do: Pass `focusableWhenDisabled` when a button disables itself mid-interaction.
- Do: Pass `touchTarget={false}` in a dense toolbar, where grown hit areas would overlap.
- Don't: Render a spinner inside `Button` by hand. `SubmitButton` owns the spinner delay.

## API reference

### Button

Renders a `button` and forwards its ref. Defaults can come from `ButtonContext`.

Slot: `cl-button`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `'primary' \| 'neutral' \| 'negative'` | `'primary'` | `primary`, `neutral` or `negative`. |
| `variant` | `'filled' \| 'outline' \| 'ghost' \| 'link'` | `'filled'` | `filled`, `outline`, `ghost` or `link`. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | `xs`, `sm`, `md` or `lg`. |
| `shape` | `'default' \| 'square' \| 'circle'` | `'default'` | `default`, `square` or `circle`. Use `square` or `circle` for an icon-only button. |
| `fullWidth` | `boolean` | `false` | Stretches to the width of the container. |
| `touchTarget` | `boolean` | `true` | Floors the hit area at the touch target size under a coarse pointer, without changing the rendered size. No effect on `link`. |
| `focusableWhenDisabled` | `boolean` | `false` | Keeps the button in the tab order while `disabled`, marked `aria-disabled` and inert to clicks. |

### SubmitButton

A `Button` for async actions. While `isPending` it goes inert and shows a spinner, keeping its width. Takes every `Button` prop; `type` defaults to `submit`, so pass `type='button'` outside a form.

Slot: `cl-button`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isPending` | `boolean` | `false` | Makes the button inert and busy. After a short delay it fades the label and centers a spinner over it. |
| `pendingLabel` | `string` | `'pending'` | Accessible name for the spinner. Pass a localized string. |
| `spinDelay` | `SpinDelayOptions` |  | `delay` before the spinner shows (default `150`) and `minDuration` it stays (default `400`). |

## Examples

### An action

```tsx
<Button variant='outline' onClick={onCancel}>Cancel</Button>
```

### A submit

```tsx
<SubmitButton isPending={form.isSubmitting}>Save</SubmitButton>
```

### An async action outside a form

```tsx
<SubmitButton type='button' onClick={onRevoke} isPending={isRevoking}>
  Revoke
</SubmitButton>
```

## Related

- [ProviderButton](/docs/components/provider-button.md)
- [useForm](/docs/hooks/use-form.md)
- [usePendingAction](/docs/hooks/use-pending-action.md)
