# Button

Triggers an action, such as submitting a form or sending a payment.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Button.tsx)

Figma: [Button](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3148), [Icon Button](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3395), [Text Button](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5601-90)

## Overview

A native `<button>` for actions. `Button.Link` renders the same styles for navigation.

## Examples

### Basic

```tsx
import { Button } from '@tempoxyz/ds'

export function Demo() {
  return <Button>Continue</Button>
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Basic.tsx)

### Variant

Set `variant` to `primary` (default), `secondary`, `tertiary`, `danger`, or `text`. A `tertiary` button has no fill until hover.

```tsx
import { Button, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['primary', 'secondary', 'tertiary', 'danger'] as const).map((variant) => (
        <Button key={variant} variant={variant}>
          Continue
        </Button>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Variant.tsx)

### Text

Set `variant="text"` for a low-emphasis action in running content, such as See more. It renders the secondary label and a trailing 12px icon without a fill or padding, and ignores `size`.

```tsx
import { Button } from '@tempoxyz/ds'
import { ChevronRight } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <Button variant="text">
      See more
      <ChevronRight />
    </Button>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Text.tsx)

### Inverse

Set `appearance="inverse"` on an inverse surface, such as a dark banner on a light page. The surface turns light in dark mode, and the button colors flip with it.

```tsx
/** Demonstrates the inverse appearance of each Button variant on an inverse surface. @module */
import { Button, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.surface()}>
      {(['primary', 'secondary', 'tertiary'] as const).map((variant) => (
        <Button appearance="inverse" key={variant} variant={variant}>
          Continue
        </Button>
      ))}
    </div>
  )
}

namespace styles {
  export const surface = style({
    alignItems: 'center',
    backgroundColor: 'inverse.background.primary',
    borderRadius: 'sm',
    display: 'flex',
    flexWrap: 'wrap',
    gap: '12',
    padding: '16',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Inverse.tsx)

### Overlay

Set `appearance="overlay"` over an image or video. The `secondary` fill is a translucent gray, and the `secondary` and `tertiary` labels stay white in both color schemes.

```tsx
/** Demonstrates the overlay appearance of each Button variant over an image. @module */
import { Button, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.image()}>
      {(['primary', 'secondary', 'tertiary'] as const).map((variant) => (
        <Button appearance="overlay" key={variant} variant={variant}>
          Continue
        </Button>
      ))}
    </div>
  )
}

namespace styles {
  // A mid-tone gradient stands in for a photo, so the labels stay legible in both color schemes.
  export const image = style({
    alignItems: 'center',
    backgroundImage: 'linear-gradient(135deg, #6b7f99, #a3866a) !custom',
    borderRadius: 'sm',
    display: 'flex',
    flexWrap: 'wrap',
    gap: '12',
    padding: '16',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Overlay.tsx)

### Size

Set `size` to `xsmall`, `small`, `medium` (default), or `large`. Heights step from 24px to 48px. `large` and `medium` take the `sm` corner radius, `small` takes `xs`, and `xsmall` renders a pill.

```tsx
import { Button, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['xsmall', 'small', 'medium', 'large'] as const).map((size) => (
        <Button key={size} size={size}>
          Continue
        </Button>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Size.tsx)

### Shape

Set `shape="icon"` for a round button that holds only an icon. The icon renders at 16px, and at 20px on a large button. Give the button an `aria-label`.

```tsx
import { Button, style } from '@tempoxyz/ds'
import { Plus as Add } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <div {...styles.row()}>
      <Button>
        <Add />
        Add funds
      </Button>
      {(['primary', 'secondary', 'tertiary'] as const).map((variant) => (
        <Button aria-label="Add" key={variant} shape="icon" variant={variant}>
          <Add />
        </Button>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Shape.tsx)

### Loading

Set `loading` to disable the button and mark it busy. The label stays visible, with a spinner centered in the leading space before it. An icon-only button shows only the centered spinner.

```tsx
import { Button, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['primary', 'secondary', 'tertiary'] as const).map((variant) => (
        <Button key={variant} loading variant={variant}>
          Loading
        </Button>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Loading.tsx)

### Disabled

```tsx
import { Button, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['primary', 'secondary', 'tertiary'] as const).map((variant) => (
        <Button disabled key={variant} variant={variant}>
          Disabled
        </Button>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Disabled.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Button } from '@tempoxyz/ds'

<Button />
<Button.Link />
```

## Guidelines

### When to Use

* Start an action in the current view, such as Send payment, Save changes, or Open settings.
* Submit a form. Set `type="submit"` on the form's main button.
* Use `Button.Link` when navigation needs a button's weight, such as Create account in an empty state.

### When Not to Use

* Use a text link for navigation inside sentences, lists, and tables.
* Use [CopyButton](/docs/components/copy-button) to copy a value, and [SplitButton](/docs/components/split-button) for a main action with related alternatives.
* Use [Tabs](/docs/components/tabs) or [ChoiceGroup](/docs/components/choice-group) to switch views, and [Switch](/docs/components/switch) to turn a setting on or off.
* If a section has more than three secondary actions, put them in a [Menu](/docs/components/menu) behind an icon button.

### Choose a Variant by Emphasis

* **Main Action (primary):** The main action of a view, dialog, or section, such as Send payment. Use one per section.
* **Supporting Actions (secondary):** Supporting actions beside a primary action, or actions of equal weight.
* **Low-Emphasis Actions (tertiary):** Dense areas, such as toolbars, table rows, and inline Cancel actions.

A destructive action takes the variant of its place in the flow, and its label names the outcome, such as Revoke key. Confirm it with an [AlertDialog](/docs/components/alert-dialog), whose confirming button takes `danger`. See [Destructive Actions](/docs/patterns/destructive-actions) and [Payments](/docs/patterns/payments).

### Use One Primary Action

Give other actions `secondary` or `tertiary`, even if they matter. [Forms](/docs/patterns/forms#submitting) sets the order of the actions.

**Do:** Pair one `primary` action with `secondary` alternatives.

```tsx
/**
 * Do example for "Use One Primary Action" on the Button page.
 * Pair one `primary` action with `secondary` alternatives.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Button variant="secondary">Cancel</Button>
      <Button>Send payment</Button>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
}
```

**Don't:** Give several actions in one section the `primary` variant.

```tsx
/**
 * Don't example for "Use One Primary Action" on the Button page.
 * Don't give several actions in one section the `primary` variant.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Button>Send</Button>
      <Button>Deposit</Button>
      <Button>Swap</Button>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
}
```

### Match Size to Context

* **Row Actions (xsmall):** A pill for an action inside a row or field, such as Copy or Edit. Never the main action.
* **Dense Layouts (small):** Tables, toolbars, cards, and icon buttons inside fields and rows, such as Export in a toolbar.
* **Default (medium):** Forms, page actions, and actions inside a dialog body, such as Copy address.
* **Dialog Footers (large):** Every action in a dialog footer, and the final step of a focused flow, such as Confirm send.

Lay out the actions in a dialog footer with a [ButtonGroup](/docs/components/button-group).

### Show Progress With Loading

**Do:** Set `loading` on the button that started the action.

```tsx
/**
 * Do example for "Show Progress With Loading" on the Button page.
 * Set `loading` on the button that started the action.
 * @module
 */
import { Button } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return <Button loading>Send payment</Button>
}
```

**Don't:** Disable the button and place a separate [Spinner](/docs/components/spinner) beside it.

```tsx
/**
 * Don't example for "Show Progress With Loading" on the Button page.
 * Don't disable the button and place a separate Spinner beside it.
 * @module
 */
import { Button, Spinner, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Button disabled>Send payment</Button>
      <Spinner aria-label="Loading" />
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

### Avoid Disabled Buttons

Keep a button enabled when you can, and show validation errors after a press. If a button must stay disabled:

* Explain why in nearby text.
* Set `focusableWhenDisabled` so keyboard users can reach it.
* Don't rely on a [Tooltip](/docs/components/tooltip). Many readers can't open it on a disabled button.

**Do:** Explain in nearby text why the button is unavailable.

```tsx
/**
 * Do example for "Avoid Disabled Buttons" on the Button page.
 * Explain in nearby text why the button is unavailable.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Button disabled focusableWhenDisabled>
        Send payment
      </Button>
      <p {...styles.hint()}>Add a recipient address to send.</p>
    </div>
  )
}

namespace styles {
  export const hint = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b3',
  })

  export const stack = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
  })
}
```

**Don't:** Disable a button without saying what is missing.

```tsx
/**
 * Don't example for "Avoid Disabled Buttons" on the Button page.
 * Don't disable a button without saying what is missing.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Button disabled>Send payment</Button>
    </div>
  )
}

namespace styles {
  export const stack = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
  })
}
```

### Use Icons to Reinforce the Label

Place an icon before the label if it aids recognition, such as a plus for Add. An icon-only button (`shape="icon"`) needs a [Tooltip](/docs/components/tooltip) with its `aria-label` text. Use it only for familiar actions, such as Close or Copy.

**Do:** Add an icon only where it aids recognition.

```tsx
/**
 * Do example for "Use Icons to Reinforce the Label" on the Button page.
 * Add an icon only where it aids recognition.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { Plus } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Button size="small" variant="secondary">
        Export
      </Button>
      <Button size="small" variant="secondary">
        Rotate key
      </Button>
      <Button size="small">
        <Plus />
        Add key
      </Button>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
}
```

**Don't:** Add icons to every button in a group.

```tsx
/**
 * Don't example for "Use Icons to Reinforce the Label" on the Button page.
 * Don't add icons to every button in a group.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { Export, Plus, Refresh } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Button size="small" variant="secondary">
        <Export />
        Export
      </Button>
      <Button size="small" variant="secondary">
        <Refresh />
        Rotate key
      </Button>
      <Button size="small">
        <Plus />
        Add key
      </Button>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
}
```

## Content

### Start With a Verb

Name the action and its object, such as Send payment or Create key.

**Do:** Repeat the action on each button, such as Revoke key and Keep key.

```tsx
/**
 * Do example for "Start With a Verb" on the Button page.
 * Repeat the action on each button, such as Revoke key and Keep key.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Button variant="secondary">Keep key</Button>
      <Button>Revoke key</Button>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
}
```

**Don't:** Use generic labels such as Yes, No, OK, or Submit.

```tsx
/**
 * Don't example for "Start With a Verb" on the Button page.
 * Don't use generic labels such as Yes, No, OK, or Submit.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Button variant="secondary">No</Button>
      <Button>Yes</Button>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
}
```

### Describe the Outcome, Not the Control

Write Continue to review, not Click here. Screen readers list buttons out of context, so each label must make sense alone.

## Accessibility

`Button` renders a native `<button type="button">`, and `Button.Link` a native `<a>`. Both follow the [WAI-ARIA button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/). See [Accessibility](/docs/foundations/accessibility) for the baseline.

### Semantics

* **Button (button):** Enter and Space activate it. Name an icon-only button with `aria-label`.
* **Button.Link (link):** Announced as a link and listed among the page's links. A modifier click opens a new tab.
* **Disabled:** Removes the button from the tab order, so keyboards skip it. Explain the reason in nearby text.
* **Focusable When Disabled (aria-disabled):** Keeps a disabled button in the tab order. It ignores every key except Tab.
* **Loading (aria-busy):** Disables the button and labels its spinner "Loading" for screen readers.
* **Icons (aria-hidden):** Hidden from assistive technology, so the button's text or label names it.

### Keyboard

* **Move to the Button (Tab):** Focuses the button, skipping disabled ones.
* **Activate the Button (Enter or Space):** Activates the button.
* **Follow a Link (Enter):** Follows a `Button.Link`.

### Your Responsibilities

* **Name Icon-Only Buttons (aria-label):** An icon-only button has no visible text. Name the action, such as "Copy address", not "Copy icon".
* **Announce Loading Results:** Loading announces only the busy state. Announce the outcome with a [Toast](/docs/components/toast) or an [Alert](/docs/components/alert).
* **Use Links for Navigation (Button.Link):** Use it for navigation, not a button with a click handler that changes the page.

## Related

[ButtonGroup](/docs/components/button-group)

Use for the actions at the foot of a dialog.

[SplitButton](/docs/components/split-button)

Use for a main action with alternatives.

[CopyButton](/docs/components/copy-button)

Use for copying a value.

[AlertDialog](/docs/components/alert-dialog)

Use for confirming an action.

[Forms](/docs/patterns/forms)

Covers placing submit and cancel actions.

[Destructive Actions](/docs/patterns/destructive-actions)

Covers deleting and revoking.
