# Button

Source: https://payloadcms.com/docs/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**

Add this override to your Admin Panel stylesheet to change primary Buttons without changing the rest of the Payload color system.

```css
.btn--style-primary {
  --bg-color: #6d5dfc;
  --color: #ffffff;
  --hover-bg: #5947e5;
  --hover-color: #ffffff;
}
```

- `--bg-color`: Button background.
- `--color`: Button label and icon color.
- `--hover-bg`: Background shown on hover, focus, and active states.
- `--hover-color`: Label and icon color shown on hover, focus, and active states.
- `--btn-border`: Optional button border.
- `--hover-btn-border`: Optional border shown on hover, focus, and active states.

## Styles

Use `secondary` for supporting actions. Use `error` when an action is destructive or difficult to reverse.

**Implementation**

```tsx
<Button margin={false}>Primary</Button>
<Button buttonStyle="secondary" margin={false}>Secondary</Button>
<Button buttonStyle="error" margin={false}>Delete</Button>
```

**Styling**

Each Button style has its own class, so a project can customize primary, secondary, and destructive actions independently.

```css
.btn--style-primary {
  --bg-color: #6d5dfc;
  --color: #ffffff;
  --hover-bg: #5947e5;
  --hover-color: #ffffff;
}

.btn--style-secondary {
  --color: #6d5dfc;
  --btn-border: 1px solid #6d5dfc;
  --hover-color: #5947e5;
  --hover-btn-border: 1px solid #5947e5;
}

.btn--style-error {
  --bg-color: #c7362f;
  --color: #ffffff;
  --hover-bg: #a92c27;
  --hover-color: #ffffff;
}
```

- `--bg-color`: Button background.
- `--color`: Button label and icon color.
- `--hover-bg`: Background shown on hover, focus, and active states.
- `--hover-color`: Label and icon color shown on hover, focus, and active states.
- `--btn-border`: Optional button border.
- `--hover-btn-border`: Optional border shown on hover, focus, and active states.

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**

Disabled styles use a more specific selector. Target both classes to customize the unavailable state without changing enabled Buttons.

```css
.btn--style-primary.btn--disabled {
  --bg-color: #e3e1f5;
  --color: #625d82;
}
```

- `--bg-color`: Disabled button background.
- `--color`: Disabled label and icon color.

## Sizes

Buttons support `xsmall`, `small`, `medium`, and `large` sizes. Use `medium` unless the surrounding interface establishes another size.

**Implementation**

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

**Styling**

Target a size class in your Admin Panel stylesheet when a project needs different Button dimensions.

```css
.btn--size-medium {
  --btn-padding-block-start: 0.5rem;
  --btn-padding-inline-end: 1rem;
  --btn-padding-block-end: 0.5rem;
  --btn-padding-inline-start: 1rem;
}
```

- `--btn-padding-block-start`: Top padding.
- `--btn-padding-inline-end`: Right padding in left-to-right layouts.
- `--btn-padding-block-end`: Bottom padding.
- `--btn-padding-inline-start`: Left padding in left-to-right layouts.

## 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' \| 'error' \| 'dashed' \| 'icon-label' \| 'pill' \| 'subtle' \| 'tab' \| 'transparent' \| 'none'` | `'primary'` | Sets the visual emphasis.                        |
| `children`    | `ReactNode`                                                                                                                 | —           | Visible button content.                          |
| `disabled`    | `boolean`                                                                                                                   | `false`     | Prevents interaction.                            |
| `icon`        | `ReactNode \| 'chevron' \| 'edit' \| 'plus' \| 'x'`                                                                         | —           | Displays an icon beside or instead of the label. |
| `margin`      | `boolean`                                                                                                                   | `true`      | Applies the default outer margin.                |
| `size`        | `'xsmall' \| 'small' \| 'medium' \| 'large'`                                                                                | `'medium'`  | Sets the button height and spacing.              |
| `type`        | `'button' \| 'submit'`                                                                                                      | `'button'`  | Sets the native button type.                     |