---
title: Button
description: >-
  A button component for triggering actions, with semantic priority levels and
  optional icon placement.
---

# Button

## Overview

Buttons enable users to perform an action, such as confirming a decision or submitting a form. They convey what actions are available and what will happen next.

```tsx
<Button label="Confirm" priority="primary" />
```

## Usage Guidelines

- **Write clear labels:** Use button labels that state the action in simple, concise language, such as "Save changes" or "Delete item." Keep labels short, use sentence case, and avoid punctuation or emojis.
- **Trigger a clear action:** Associate each button with a relevant action, such as submitting data or confirming a decision. If the action takes time to complete, show the button in a pending state after activation.
- **Use priority intentionally:** Use a primary button to represent the main action within a page or section. Use secondary and tertiary buttons for supporting actions. Priority is relative within the current action group, and levels can be skipped.

## API Reference

### `Button`

| Prop           | Type                                     | Default      |
| -------------- | ---------------------------------------- | ------------ |
| `compact`      | `boolean`                                | `false`      |
| `disabled`     | `boolean`                                | `false`      |
| `destination`  | `string`                                 | `undefined`  |
| `icon`         | `ReactNode`                              | `undefined`  |
| `iconPosition` | `"start" \| "end"`                       | `"start"`    |
| `label`        | `string`                                 | `undefined`  |
| `pending`      | `boolean`                                | `false`      |
| `priority`     | `"primary" \| "secondary" \| "tertiary"` | `"tertiary"` |

## Examples

### Pending

Use the pending state after activation when an action takes time to complete. Avoid it for immediate actions.

```tsx
<Button label="Create account" priority="primary" pending />
```

### Compact

Use compact buttons in dense layouts such as toolbars, tables, or tightly grouped controls. Prefer the default button in most cases.

```tsx
<Button label="Publish" priority="primary" compact />
<Button priority="secondary" compact icon={<EditIcon />} aria-label="Edit" />
```

### Priority

Use priority to reflect action importance. Primary is for the main action in a section, while secondary and tertiary are for supporting actions.

```tsx
<Button label="Confirm" priority="primary" />
<Button label="Search" priority="secondary" />
<Button label="Cancel" priority="tertiary" />
```

### Icons

Use icons to reinforce a button's meaning. Reserve icon-only buttons for common actions in dense interfaces, and always provide an accessible text label.

```tsx
<Button label="Bookmark" icon={<BookmarkIcon />} priority="primary" />
<Button label="Continue" icon={<ArrowRightIcon />} iconPosition="end" priority="secondary" />
<Button icon={<CheckIcon />} priority="tertiary" aria-label="Complete task" />
```