# Button

The main action trigger, in 11 variants, 2 shapes and 5 sizes.

- Category: Core Elements
- Page: https://wunderui.com/components/button
- Tier: Free

## Install

```bash
npx wunderui-cli add button
```

## Import

```tsx
import { Button, ButtonCell, ButtonPhase } from "@/components/ui/button"
```

## Minimal usage

Then use it:

```tsx
import { Button } from "@/components/ui/button"

export function SaveButton() {
  return <Button>Save changes</Button>
}
```

Expected result: You see one 36 px button with the primary indigo fill and the label Save changes.

## Usage

```tsx
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <Button variant="primary">Save changes</Button>
  )
}
```

## When to use

### Use Button for

- An action on the current page: save, send, invite, open a dialog
- The one main action of a view, as a Primary or Gradient button, with Plain buttons for the actions next to it
- A link-styled action inside a sentence or a card, with the Link variant

### Use something else

- [Icon Button](https://wunderui.com/components/icon-button) for an action that is only an icon, such as close, copy or more
- [Button Group](https://wunderui.com/components/button-group) for a few related actions joined into one control, or a split button with a menu
- [Toggle](https://wunderui.com/components/toggle) for a button that stays on or off
- [Segment](https://wunderui.com/components/segment) for exactly one choice out of a few options
- [Dropdown Menu](https://wunderui.com/components/dropdown-menu) for many actions behind one button

## Keyboard

Button is a native button, so the browser handles focus and activation.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to or away from the button. A disabled button is skipped; a pending one keeps the focus. |
| `Enter` or `Space` | Presses the button. While it is pending, the press is ignored. |

## Behavior

What the button does with state, content, the DOM and motion.

- **Variants:** Eleven variants: Plain is the ordinary button, Primary and Gradient are calls to action, and link reads as text. Ghost is for icon-only controls, plain for labelled buttons.
- **Size and density:** Sizes run from small to 2xl: 32 to 48 px at compact density and 36 to 56 px at comfortable, because height and padding follow the density setting.
- **States:** Hover and press darken the fill, and pressing scales the button to 0.97. Focus draws an indigo border and a 2 px ring, and disabled dims to 40 % and ignores the pointer.
- **Pending:** Pending swaps the leading icon for a spinner and ignores presses. The button stays focusable and keeps its colour, so it is not disabled.
- **Phase:** Phase is idle, pending, success or error. The icon slot shows a spinner, a check or a retry icon, a filled button turns red on error, and you write the label.
- **As a link:** Render the button as an anchor to get a link that looks like a button, for moving to another page.
- **Motion:** Fill and border change quickly. A press scales the button to 0.97 and the pending spinner turns continuously.
- **Reduced motion:** With reduced motion the press scale and spinner rotation are off. The fills still change at the same speed.

## Anatomy

- `Button`: A native button that fits its content. Variant sets the look, size the height (32 to 48 px), shape rounded or pill, and pending shows a spinner and ignores presses.
- `Leading icon`: An icon before the label, with 2 px less padding on that side. It is 16 px at small and medium, up to 24 px at the largest sizes, and a spinner replaces it while pending.
- `Label`: The text, 14 px medium (16 px at xl, 18 px at 2xl). Write a verb and its object, such as Save changes, and keep it on one line.
- `Trailing icon`: An icon after the label, for a direction such as an arrow or a chevron.
- `ButtonCell`: A small plain button for a secondary action in a table row.

## Best practices

### When to use

- Use a Button for an action on the current page, such as save, send or open a dialog. To go to another page, render the button as a link.

### Do

- Give each view one primary or gradient button for its main action. Other actions are plain or links, and icon-only controls in a row, toolbar, field or card are ghost IconButtons.
- Label a button with a verb and its object, like Save changes or Invite member. A destructive button repeats its action, and the one beside it says Cancel.
- Show an async result on the button itself: Save changes, Saving, Saved, Retry. Give it a fixed width so it does not jump, and explain an error in a message nearby.
- Give an icon-only control an aria-label and build it with IconButton, not a Button with an icon and no label.

### Don't

- Don't use outline for ordinary secondary actions. Those are plain; outline is an indigo-rimmed accent for the rare case that needs one.
- Don't set heights or padding by hand. Pick a size, so compact and comfortable density both stay right.
- Don't make destructive the default button. Name the action, like Delete workspace, and put a plain Cancel next to it.
- Don't disable a button without saying why. Explain it in a message or tooltip, or keep the button enabled and explain the error after the press.

## API reference

### Button

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with its own, or a function that returns them from the state of the button. Use it for a fixed width such as `w-37`, not for the height. |
| focusableWhenDisabled | boolean | false | Keeps a disabled button in the tab order, so a screen reader user can find it and read why it is disabled. |
| nativeButton | boolean | true | Whether the component renders a native `<button>`. Set it to `false` together with `render` when the element is not a button, such as an anchor. |
| pending | boolean |  | Shows a spinner in place of the leading icon, sets `aria-busy` and ignores presses. The button stays focusable and keeps its colour. |
| phase | "error" \| "success" \| "pending" \| "idle" |  | Async feedback: `pending` shows a spinner, `success` a check, `error` a retry icon and turns a filled button red. The label is yours, for example `Saving…`, `Saved`, `Retry`. Give the button a fixed width so it does not jump. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element, for example with a link: `render={<a href="/billing" />}` together with `nativeButton={false}`. Accepts an element or a function that returns one. |
| shape | "rounded" \| "pill" | "rounded" | `rounded` has a medium corner radius, `pill` is fully rounded. |
| size | "lg" \| "xl" \| "sm" \| "md" \| "2xl" | "md" | The height: `sm` is 32 px, `md` 36, `lg` 40, `xl` 44 and `2xl` 48 at the compact density (36 to 56 at the comfortable one). Padding, text and icon size follow. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles, or a function that returns them from the state of the button. |
| variant | "link" \| "plain" \| "gradient" \| "outline" \| "primary" \| "destructive" \| "light" \| "ghost" \| "brand" \| "dark" \| "tint" | "primary" | The look. `plain` is the ordinary button, `primary` and `gradient` are for the main action, `brand` is the brand fill, `dark` and `light` are for surfaces of the opposite tone, `outline` is an indigo-rimmed accent, `tint` is the selected look, `ghost` has no box and no fill until hover (for icon-only controls in a row, toolbar, field or card; use `plain` for labelled buttons), `destructive` is red and `link` reads as text. |

Also accepts React.ButtonHTMLAttributes attributes.

### ButtonCell

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The label of the cell button. |
| onClick | () => void |  | Runs when the cell button is pressed. |

## Examples

### Appearance: eleven variants

```tsx
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <Button variant="primary">Save changes</Button>
  )
}
```

### Shape: rounded or pill

```tsx
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <Button shape="rounded">Save changes</Button>
  )
}
```

### Size: 32, 36, 40, 44 and 48 px

```tsx
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <Button size="md">Save changes</Button>
  )
}
```

### Icons: none, leading or trailing

```tsx
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <Button>Add item</Button>
  )
}
```

### States: default, hover, pressed, focus, disabled and loading

```tsx
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <Button variant="plain">Cancel</Button>
  )
}
```

### Async feedback: idle, pending, success and error

```tsx
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <Button className="w-37">Save changes</Button>
  )
}
```

### Button with a count

A count badge sits after the label, for inboxes, filters and carts. The button keeps the plain style.

```tsx
<Button variant="plain">
  Inbox
  <Badge color="grey" badgeStyle="light" shape="pill">12</Badge>
</Button>
```

### Button with a status dot

A small dot before the label shows a state at a glance. Colour is never the only signal, the label says it too.

```tsx
<Button variant="plain">
  <span aria-hidden className="size-2 rounded-full bg-success" />
  Online
</Button>
```

### Plain button with a status badge

A plain button with a badge that names the state.

```tsx
<Button variant="plain">
  <Bell />
  Notifications
  <Badge color="red" badgeStyle="light" shape="pill">3 new</Badge>
</Button>
```

### Sliding icon on hover

On hover or focus the label steps aside and an arrow slides in from the left. Only transform and opacity move.

```tsx
<Button className="relative px-6">
  <span className="transition-transform duration-base ease-entrance group-hover/button:translate-x-2.5">
    Continue
  </span>
  <ArrowRight
    aria-hidden
    className="absolute left-3 -translate-x-2 opacity-0 transition-[transform,opacity] duration-base ease-entrance group-hover/button:translate-x-0 group-hover/button:opacity-100"
  />
</Button>
```

## In context

### Dialog footer: Cancel and one main action

A plain Cancel sits next to the main action, which is destructive when the dialog deletes something.

```tsx
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <div className="max-w-md rounded-xl border border-border bg-card p-6">
      <p className="text-base font-semibold">Unsaved changes</p>
      <p className="mt-1 text-sm text-text-secondary">
        Save the new billing details for WunderUI before you leave this page.
      </p>
      <div className="mt-6 flex justify-end gap-3">
        <Button variant="plain">Cancel</Button>
        <Button>Save changes</Button>
      </div>
    </div>
  )
}
```

### Save flow: Save changes, Saving, Saved or Retry

Press the button to run the flow. If the request fails, the button turns red and offers Retry.

```tsx
import { useEffect, useRef, useState } from "react"
import { Button, type ButtonPhase } from "@/components/ui/button"

const LABEL: Record<ButtonPhase, string> = {
  idle: "Save changes",
  pending: "Saving…",
  success: "Saved",
  error: "Retry",
}

export function Example() {
  const [phase, setPhase] = useState<ButtonPhase>("idle")
  const timer = useRef<ReturnType<typeof setTimeout>>(undefined)

  // keep the timer in a ref and clear it when the component unmounts
  useEffect(() => () => clearTimeout(timer.current), [])

  function save() {
    setPhase("pending")
    timer.current = setTimeout(() => {
      // replace this with your request: success when it resolves, error when it fails
      setPhase("success")
      timer.current = setTimeout(() => setPhase("idle"), 2000)
    }, 1200)
  }

  return (
    <div className="flex items-center justify-between gap-4 rounded-xl border border-border bg-card p-4">
      <div className="flex flex-col">
        <span className="text-sm font-medium">Billing email</span>
        <span className="text-sm text-text-secondary">info@wunderui.com</span>
      </div>
      {/* A fixed width keeps the button from jumping between the four labels. */}
      <Button className="w-37" phase={phase === "idle" ? undefined : phase} onClick={save}>
        {LABEL[phase]}
      </Button>
      <span role="status" className="sr-only">
        {phase === "success" ? "Saved" : ""}
      </span>
    </div>
  )
}
```

### Copy link: a button that confirms itself

The label changes to Copied for two seconds, so nobody wonders whether the press worked.

```tsx
import { useEffect, useRef, useState } from "react"
import { Link2 } from "lucide-react"
import { Button } from "@/components/ui/button"

export function Example() {
  const [phase, setPhase] = useState<"idle" | "success" | "error">("idle")
  const timer = useRef<ReturnType<typeof setTimeout>>(undefined)

  useEffect(() => () => clearTimeout(timer.current), [])

  async function copy() {
    try {
      await navigator.clipboard.writeText("https://wunderui.com/s/q3-roadmap")
      setPhase("success")
      timer.current = setTimeout(() => setPhase("idle"), 2000)
    } catch {
      setPhase("error")
    }
  }

  return (
    <div className="flex items-center gap-2 rounded-xl border border-border-control bg-card p-2">
      <span className="min-w-0 flex-1 truncate px-2 text-sm text-text-secondary">wunderui.com/s/q3-roadmap</span>
      <Button variant="plain" size="sm" className="w-28" phase={phase === "idle" ? undefined : phase} onClick={copy}>
        {phase === "idle" && <Link2 data-icon="inline-start" />}
        {phase === "success" ? "Copied" : phase === "error" ? "Retry" : "Copy link"}
      </Button>
    </div>
  )
}
```

### Pagination: Previous and Next

Plain buttons with a leading and a trailing icon. At the end of the list the button that cannot move is disabled.

```tsx
import { useState } from "react"
import { ChevronLeft, ChevronRight } from "lucide-react"
import { Button } from "@/components/ui/button"

const PAGES = 12

export function Example() {
  const [page, setPage] = useState(1)

  return (
    <nav aria-label="Pagination" className="flex items-center justify-between gap-3">
      <Button variant="plain" disabled={page === 1} onClick={() => setPage(page - 1)}>
        <ChevronLeft data-icon="inline-start" />
        Previous
      </Button>
      <span className="text-sm text-text-secondary">
        Page {page} of {PAGES}
      </span>
      <Button variant="plain" disabled={page === PAGES} onClick={() => setPage(page + 1)}>
        Next
        <ChevronRight data-icon="inline-end" />
      </Button>
    </nav>
  )
}
```

### Checkout: full width on a phone

On a narrow screen the buttons fill the row and keep the large size. Turn on the mobile width to see it at 390 px.

```tsx
import { Button } from "@/components/ui/button"

export function Example({ processing = false }: { processing?: boolean }) {
  return (
    <div className="flex flex-col gap-4 rounded-xl border border-border bg-card p-4">
      <dl className="flex flex-col gap-1 text-sm">
        <div className="flex justify-between">
          <dt className="text-text-secondary">Subtotal</dt>
          <dd>$69.98</dd>
        </div>
        <div className="flex justify-between">
          <dt className="text-text-secondary">Tax</dt>
          <dd>$5.60</dd>
        </div>
        <div className="flex justify-between font-semibold">
          <dt>Total</dt>
          <dd>$75.58</dd>
        </div>
      </dl>
      {/* On a phone the buttons fill the row and keep the large size. */}
      <div className="flex flex-col gap-2">
        <Button size="lg" className="w-full" pending={processing}>
          {processing ? "Processing…" : "Continue to payment"}
        </Button>
        <Button variant="plain" size="lg" className="w-full">
          Back to cart
        </Button>
      </div>
    </div>
  )
}
```

## For AI agents

`get_component("button")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
