# Button

Headless, unstyled button that can stay focusable while disabled, and gives button semantics to an element that is not a `<button>`. Sets `data-disabled` while disabled.

## Use for

- a button that disables itself mid-interaction without dropping focus
- button semantics on a link or a `span`
- the base for a styled button component

## Practices

- Do: Pass `focusableWhenDisabled` when the button disables itself while work runs, such as a submit.
- Do: Pass `nativeButton={false}` whenever `render` returns an element that is not a `<button>`.
- Do: For a styled action, use `Button` or `SubmitButton` from `src/components/button` instead.

## API reference

### Button

Renders a `button`, or the `render` element, and forwards its ref. A native button gets `type="button"` unless you pass `type`. While disabled, clicks, pointer presses and keys other than `Tab` do nothing and the caller's handlers do not run.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Makes the button inert. |
| `focusableWhenDisabled` | `boolean` | `false` | Keeps a disabled button in the tab order, marked `aria-disabled` instead of `disabled`. |
| `nativeButton` | `boolean` | `true` | Set `false` when `render` is not a `<button>`, to add `role="button"`, a tab stop, and Enter and Space activation. |

## Examples

### Focus survives a submit

```tsx
<Button type='submit' disabled={submitting} focusableWhenDisabled>
  Save
</Button>
```

### Button semantics on a link

```tsx
<Button nativeButton={false} render={<a href='/settings' />}>
  Settings
</Button>
```
