# Button

Source: https://payloadcms.com/docs/beta/ui-components/button

The `Button` component lets a user perform an action or navigate to another location. Use its style to communicate the importance and consequence of the action.

## Import

Inside a Payload Admin Panel Custom Component:

```tsx
import { Button } from '@payloadcms/ui'
```

You can also import the component directly:

```tsx
import { Button } from '@payloadcms/ui/elements/Button'
```

## Basic usage

Use a primary button for the main action in a section or view.

**Implementation**

```tsx
<Button margin={false}>Save changes</Button>
```

**Styling**

Scope Payload 4 semantic color tokens to primary Buttons to customize the component without changing the global brand palette.

```css
@layer payload {
  .btn--style-primary {
    --color-bg-brand: #6d5dfc;
    --color-bg-brand-hover: #5947e5;
    --color-bg-brand-pressed: #4938cc;
    --color-text-onbrand: #ffffff;
  }
}
```

- `--color-bg-brand`: Primary button background.
- `--color-bg-brand-hover`: Primary button background on hover.
- `--color-bg-brand-pressed`: Primary button background while pressed.
- `--color-text-onbrand`: Button label and icon color.

## Styles

Use `secondary` for supporting actions. Use `destructive` when an action is destructive or difficult to reverse. The `dashed`, `ghost`, and `pill` variants provide lower-emphasis treatments for controls that need them.

**Implementation**

```tsx
<Button margin={false}>Primary</Button>
<Button buttonStyle="secondary" margin={false}>Secondary</Button>
<Button buttonStyle="destructive" margin={false}>Delete</Button>
<Button buttonStyle="dashed" margin={false}>Dashed</Button>
<Button buttonStyle="ghost" margin={false}>Ghost</Button>
<Button buttonStyle="pill" margin={false}>Pill</Button>
```

**Styling**

Each Button variant has its own class, so supporting and destructive actions can be customized independently.

```css
@layer payload {
  .btn--style-secondary {
    --color-bg: #f7f5ff;
    --color-text: #4938cc;
    --special-border-translucent: #8b7cf6;
  }

  .btn--style-destructive {
    --color-bg-danger: #c7362f;
    --color-bg-danger-hover: #a92c27;
    --color-bg-danger-pressed: #8f2420;
    --color-text-ondanger: #ffffff;
  }
}
```

- `--color-bg`: Secondary button background.
- `--color-text`: Secondary button label and icon color.
- `--special-border-translucent`: Secondary button border color.
- `--color-bg-danger`: Destructive button background.
- `--color-bg-danger-hover`: Destructive button background on hover.
- `--color-bg-danger-pressed`: Destructive button background while pressed.
- `--color-text-ondanger`: Destructive button label and icon color.

Avoid placing multiple primary buttons next to one another. When actions have equal emphasis, use secondary buttons instead.

## Disabled state

Use `disabled` when an action is temporarily unavailable. When possible, explain what the user must do before the action becomes available.

**Implementation**

```tsx
<Button disabled margin={false}>Save changes</Button>
```

**Styling**

Target the disabled state together with a style variant to customize unavailable Buttons without changing enabled actions.

```css
@layer payload {
  .btn--style-primary.btn--disabled {
    --color-bg-disabled: #e3e1f5;
    --color-text-ondisabled: #625d82;
  }
}
```

- `--color-bg-disabled`: Disabled button background.
- `--color-text-ondisabled`: Label and icon color on a disabled filled button.

## Sizes

Buttons support `medium` and `large` sizes. Use `medium` unless the surrounding interface establishes the larger size.

**Implementation**

```tsx
<Button margin={false} size="medium">Medium</Button>
<Button margin={false} size="large">Large</Button>
```

**Styling**

Override the spacing tokens within a size class when a project needs different Button dimensions.

```css
@layer payload {
  .btn--size-medium {
    --button-height: 1.75rem;
    --spacer-2: 0.625rem;
  }

  .btn--size-large {
    --spacer-5: 2.25rem;
    --spacer-3: 0.875rem;
  }
}
```

- `--button-height`: Medium button height.
- `--spacer-2`: Medium button inline padding.
- `--spacer-5`: Large button height.
- `--spacer-3`: Large button inline padding.

## Accessibility

- Use a short, action-oriented label that describes what happens next.
- Provide `aria-label` when an icon-only button has no visible label.
- Do not rely on color alone to explain a destructive or disabled action.
- Use `type="submit"` only when the button submits its containing form.
- Use a link-style button for navigation rather than handling navigation in `onClick`.

## Common props

These are the props most commonly used with this component. See its exported types in `@payloadcms/ui` for the complete list.

| Prop          | Type                                                                         | Default     | Description                                                   |
| ------------- | ---------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------- |
| `buttonStyle` | `'primary' \| 'secondary' \| 'destructive' \| 'dashed' \| 'ghost' \| 'pill'` | `'primary'` | Sets the visual emphasis.                                     |
| `children`    | `ReactNode`                                                                  | —           | Visible button content.                                       |
| `disabled`    | `boolean`                                                                    | `false`     | Prevents interaction.                                         |
| `loading`     | `boolean`                                                                    | `false`     | Shows a spinner, hides the content, and prevents interaction. |
| `margin`      | `boolean`                                                                    | `true`      | Applies the default outer margin.                             |
| `round`       | `boolean`                                                                    | `false`     | Gives an icon button equal width and height.                  |
| `selected`    | `boolean`                                                                    | `false`     | Applies the active treatment to supported variants.           |
| `size`        | `'medium' \| 'large'`                                                        | `'medium'`  | Sets the button height and spacing.                           |
| `type`        | `'button' \| 'submit'`                                                       | `'button'`  | Sets the native button type.                                  |