Button
FreeRun an action on the current page, such as save, send or open a dialog.
npx wunderui-cli add buttonPlayground
Installation
npx wunderui-cli add buttonWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Button } from "@/components/ui/button"
import type { ButtonPhase } from "@/components/ui/button"Then use it:
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.
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 for
- Icon Button for an action that is only an icon, such as close, copy or more
- Button Group for a few related actions joined into one control, or a split button with a menu
- Toggle for a button that stays on or off
- Segment for exactly one choice out of a few options
- Dropdown Menu for many actions behind one button
Appearance
Plain is the ordinary button. Primary and Gradient are for the one main action of a view, the other variants for surfaces and rare cases.
Shape
Rounded is the default. Use the pill when the buttons sit next to other fully rounded controls.
Sizes
Five heights, small to 2xl. Height and padding follow the density tokens, so never set them by hand.
Size
Icons
An icon goes before the label, or after it to show direction. Mark it with data-icon and it grows with the button.
States
Hover, pressed and focus are forced here to show what the pointer and keyboard produce. Loading keeps the label and the colour.
Async feedback
The result of a request shows on the button itself. Give the button a fixed width so it does not jump between the four labels.
Keyboard interactions
Button is a native button, so the browser handles focus and activation.
- TaborShift+Tab
- Moves focus to or away from the button. A disabled button is skipped; a pending one keeps the focus.
- EnterorSpace
- Presses the button. While it is pending, the press is ignored.
Behavior and motion
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
A button is one element: the icons are children you mark, and the label is the text between them.
- 1data-slot="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.
- 2Optional
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.
- 3
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.
- 4Optional
An icon after the label, for a direction such as an arrow or a chevron.
- Optional
A small plain button for a secondary action in a table row.
Best practices
- 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.
- Do
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.
- Do
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.
- Do
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
Don't set heights or padding by hand. Pick a size, so compact and comfortable density both stay right.
- Don’t
Don't make destructive the default button. Name the action, like Delete workspace, and put a plain Cancel next to it.
- Don’t
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 wraps the Base UI button, so it accepts all native button attributes and can be rendered as another element.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "link" | "plain" | "gradient" | "outline" | "primary" | "destructive" | "light" | "ghost" | "brand" | "dark" | "tint" | "primary" | The look. is the ordinary button, and are for the main action, is the brand fill, and are for surfaces of the opposite tone, is an indigo-rimmed accent, is the selected look, has no box and no fill until hover (for icon-only controls in a row, toolbar, field or card; use for labelled buttons), is red and reads as text. |
| size | "lg" | "xl" | "sm" | "md" | "2xl" | "md" | The height: is 32 px, 36, 40, 44 and 48 at the compact density (36 to 56 at the comfortable one). Padding, text and icon size follow. |
| shape | "rounded" | "pill" | "rounded" | has a medium corner radius, is fully rounded. |
| pending | boolean | — | Shows a spinner in place of the leading icon, sets and ignores presses. The button stays focusable and keeps its colour. |
| phase | "error" | "success" | "pending" | "idle" | — | Async feedback: shows a spinner, a check, a retry icon and turns a filled button red. The label is yours, for example , , . Give the button a fixed width so it does not jump. |
| nativeButton | boolean | true | Whether the component renders a native . Set it to together with when the element is not a button, such as an anchor. |
| 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. |
A small plain button for a secondary action in a table row.
| Prop | Type | Default | Description |
|---|---|---|---|
| children required | ReactNode | — | The label of the cell button. |
| onClick | () => void | — | Runs when the cell button is pressed. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("button")npx wunderui-cli add buttonThe full library index for assistants is at /llms.txt.