Button
updatedYes, it's a button. You click it, it does things. We're as surprised as you are.
Open Props in the corner of the example to try variant, color, size and disabled. The code follows.
variant is the look, color is the colour. 6 × 6 = 36 combos, and all of them work. Yes, even a destructive ghost. Defaults: solid + primary.
subtle is soft with an edge, so it survives tinted backgrounds and button groups. The edge is an inset ring, not a border, so swapping variants never moves the layout.
size runs xs to xl on the control scale, md by default, so a button lines up with an input of the same size. An icon alone takes an icon-* size instead: a square of the same height (see Icons).
Installation
Usage
<script setup lang="ts">
import { Button } from '@/components/ui/button'
</script>
<template>
<Button variant="outline" color="neutral">Button</Button>
</template>
Examples
Custom colours
Need a colour we didn't ship? Three variables and a name:
@layer base {
[data-slot][data-color='pro'] {
--tone: var(--color-violet-600); /* fill */
--tone-foreground: white; /* text on the fill */
--tone-text: var(--color-violet-700); /* text without a fill */
}
}
<Button color="pro">Upgrade</Button>
It works with every variant. Soft fills and edges are derived from these three. The full variable list lives in Theming.
Keep the rule in @layer base, where the built-in colours live. Outside any layer it beats every utility, so an invalid Switch or Checkbox in your colour would keep it instead of turning destructive.
Just for one button? Skip the CSS:
<Button class="[--tone:var(--color-pink-500)] [--tone-foreground:white] [--tone-text:var(--color-pink-700)]">
Upgrade
</Button>
Icons
An icon inside a button should say which side it sits on, with data-icon="inline-start" or data-icon="inline-end". The button then tightens padding on that side only; a rule keyed on svg would pull in both sides at once and cramp the label against the far edge. Spinner sets data-icon="inline-start" itself, so the ordinary case needs nothing from you.
Loading
No loading prop. Bring your own spinner, ours or anyone else's:
Saves: 0
As a link
as renders another element; as-child merges the button onto the single element you pass.
Focus ring
A host that clips overflow cuts off the default outward ring, and a keyboard user gets no indicator at all. focus-ring="inward" draws it inside. Tab through both.
Touch target
Smaller than a finger? Add touch-target: expand when it stands alone, wrapper when it sits close to others. How it works.
API Reference
Button
class is also accepted and merged over the variant classes with tailwind-merge.
| Prop | Default | Type and description |
|---|---|---|
| variant | "solid" | "solid" | "soft" | "subtle" | "outline" | "ghost" | "link" | nullAppearance, independent of colour. |
| color | "primary" | ButtonColor | (string & {})Colour role the variant is drawn in. |
| size | "md" | ButtonSizeHeight, padding and text size, |
| touchTarget | "none" | "none" | "expand" | "wrapper" | nullGrows the pressable area to at least 48px without changing how the button looks. |
| focusRing | "outward" | "outward" | "inward" | nullWhere the focus ring is drawn. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the button's attributes and classes onto it. |
| as | "button" | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}Label and icons. Mark an icon with |
class is also accepted and merged over the variant classes with tailwind-merge.
Props
- variant
"solid" "solid" | "soft" | "subtle" | "outline" | "ghost" | "link" | nullAppearance, independent of colour.- color
"primary" ButtonColor | (string & {})Colour role the variant is drawn in.neutraluses the page's own foreground. Any other name picks up a colour you declare on[data-slot][data-color="<name>"].- size
"md" ButtonSizeHeight, padding and text size,xstoxl. Theicon-*sizes are squares of the same heights, for an icon alone.- touchTarget
"none" "none" | "expand" | "wrapper" | nullGrows the pressable area to at least 48px without changing how the button looks.wrapperalso reserves that space in layout;expandmay overlap neighbours.- focusRing
"outward" "outward" | "inward" | nullWhere the focus ring is drawn.inwardstays visible inside a host that clips overflow.- asChild
booleanRender the single child instead of a wrapper, merging the button's attributes and classes onto it.- as
"button" AsTag | ComponentThe element or component to render.
Slots
- default
{}Label and icons. Mark an icon withdata-icon="inline-start"or"inline-end"to tighten padding on that side.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| button | data-variant, data-color, data-size | The root element, or your own element under as-child. All three are set even when left at their defaults, solid, primary and md. |
Accessibility
| Key | Action |
|---|---|
| Enter | Activates the button. |
| Space | Activates the button. |
Native disabled takes the button out of the tab order: if it had focus, the browser moves focus to <body>, so a keyboard user loses their place at the moment they act. It also stops pointer events, so a tooltip cannot say why the button is off. aria-disabled="true" draws the same disabled look but keeps focus and pointer events; the button swallows its click, so neither a press nor Enter or Space reaches your handler. See W3C's guidance on disabled controls.