Button

updated

Yes, it's a button. You click it, it does things. We're as surprised as you are.

Demo

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.

With icons

Loading

No loading prop. Bring your own spinner, ours or anyone else's:

Loading

Saves: 0

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.

Focus ring

Touch target

Smaller than a finger? Add touch-target: expand when it stands alone, wrapper when it sits close to others. How it works.

Touch target

API Reference

Data attributes

data-slotAttributesDescription
buttondata-variant, data-color, data-sizeThe root element, or your own element under as-child. All three are set even when left at their defaults, solid, primary and md.

Accessibility

KeyAction
EnterActivates the button.
SpaceActivates 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.

Changelog

  1. registry 0.22.0

    4712efa — A Kbd inside a Button wrapped in TooltipTrigger as-child (or any other as-child trigger) keeps the button's colours, and an InputGroupButton wrapped the same way in a block addon keeps the addon's inset. The trigger's data-slot replaces the child's own, as in shadcn, so Kbd now keys on the <button> element (any button tints it, Toggle and Toolbar items included) and the block addon sets the inset on its children.

    28514cf — Button transitions with Tailwind's default transition list instead of transition-colors, so <Button class="press-scale"> dips while held. The dip takes Button's own duration; --press-duration applies to elements without a transition of their own.

    13863fd — A disabled Pagination disables its as-child link pages as well: they carry aria-disabled, look disabled and do not navigate. Button pages carry aria-disabled next to their native disabled.

    9a6eefe — A bare <Spinner /> is 1em square, the size of the surrounding text, instead of as wide as its container; a size class or a Button still sizes it. Its styles sit in @layer components, so a class such as animate-none now replaces its animation.

    ac9afad — An aria-disabled Toggle, ToggleGroupItem or ToolbarToggleItem ignores click, Enter and Space like an aria-disabled Button, so a toolbar toggle kept focusable for its tooltip no longer changes the model. swallowWhenDisabled moves to @/ui/button, where the three parts share it.

  2. registry 0.21.0

    e5495ef — size works the same way everywhere. Every component exports its size type (AlertSize, BadgeSize, CardSize, CheckboxSize, RadioSize, SwitchSize, EmptySize, InputFloatingSize, ItemSize, ListboxSize, SeparatorSize, SliderSize, StepperSize, TabsSize, TextareaSize, TimelineSize) and the props take it without null; Button-based parts take ButtonSize, Input TextControlSize, SelectTrigger SelectSize and Tree TreeSize. ToggleGroup and ToolbarToggleGroup carry data-size on the group as well. Table's row heights moved into tableSize, so a class on DataTable's ui.table overrides --table-row-h at every size, not only at md.

  3. registry 0.15.0

    d09f26a — Pressable parts ripple on their own: Button, Toggle, ToggleGroupItem, Item as a link or a button, the calendar days, tabs, accordion, menubar and navigation menu triggers, the items of Menu, Menubar, Select, Combobox, Command, DrawerMenu, Listbox and Tree, and the clear buttons of TagsInput and Combobox. Each imports the directive from @/lib/ripple, so add brings the ripple item along and nothing needs registering. On menu, listbox and tree rows the wave replaces the pressed layer, as state-layer already did. Bind v-ripple="false" on a Button to turn one off, or set --kappa-ripple: none on :root to turn them all off.

  4. registry 0.14.0

    2add2d3 — FileUpload is built from parts, after Dice UI's anatomy: FileUpload (the files, the checks, the hidden input, paste, Field wiring and size), FileUploadDropzone (drops and a click, variant), FileUploadTrigger (the button that opens the dialog, as-child for a Button), FileUploadIcon, FileUploadTitle, FileUploadDescription, FileUploadList (layout list or grid), FileUploadItem, FileUploadItemPreview, FileUploadItemMetadata, FileUploadItemDelete and FileUploadClear, plus fileKey(file) for v-for keys. The zone that is one button is FileUploadDropzone as-child on the trigger; a zone with a Browse button holds an as-child trigger and is no tab stop itself. The props mode, layout, position, label, description, icon, file-icon, file-image, file-delete, preview, interactive and dropzone, the 14 slots and the exposed triggerEl are gone: compose the parts instead, and put a ref on the trigger for Formisch. removeFile takes the file, not an index. A trigger without a dropzone no longer takes drops.

  5. registry 0.13.0

    11239a6 — New Rating component, on Reka UI's Rating: a row of stars to pick a score in whole, half, quarter or tenth steps. It takes size from xs to xl on the control tokens, so it lines up with a Button of the same size, and color like the other choice controls, with warning for gold stars. hoverable previews the value under a mouse or a pen but never under a finger, clearable takes the score back, and touch-target, vertical and right-to-left layouts and icon and empty-icon slots work as elsewhere.

    readonly shows an exact value, 4.3 fills the fifth star to 30%, as one picture named "Rated 4.3 out of 5", with no radios for screen readers to announce. In a Field it takes the field's id, label, description, error, invalid, required and disabled state. In a plain form, a rating with nothing picked, or cleared, submits an empty value, so native required holds until a star is picked.

    5a478d3 — Checkbox, Radio, Switch, Slider, Progress, Stepper and TabsList take color: primary (the default), neutral, destructive, success, warning, info, or any name you declare on [data-slot][data-color="<name>"], as on Button. The root carries data-color. Whatever they draw straight on the page takes the colour's --tone-text: a checked edge, the radio's dot, the default slider's range and thumb, the progress bar and the tab line. That keeps a bright success, warning or info at 3:1 against the page. Fills with something on them, like the checked box, the switch track and the active step, keep --tone. On the choice controls the unchecked edge stays --input and an invalid control still turns destructive. Keyboard focus rings a control in a colour other than primary in its --tone-text, red once it's invalid. CheckboxGroup and RadioGroup pass their color to every control in them without one, and ChoiceGroup takes color for the selected card's edge, the focused card's ring and the selected row's tint. Switch, Checkbox, Radio and Slider now set data-size, md by default. They need the @kappa-ui/core release that lets tone-control follow data-color.

    Recoloured Switch, Checkbox, Radio or Slider with class="[--tone:…] [--tone-foreground:…]", as the theming page used to suggest? Their edges and marks now read --tone-text, so add [--tone-text:…] to the class, or use color.

    277f092 — New FileUpload: a drop zone (mode="area") or a Button (mode="button") that picks files into a File or, with multiple, a File[] v-model. Files come from the dialog, a drop or a paste, and all three go through accept, max-size and max-files, so a file of the wrong type never reaches the model even when the user picks "All files" in the dialog; whatever is turned away comes back through reject with a reason. Files show as a list or a grid of thumbnails, under the frame or inside it, with a Remove button each that moves focus to the next one. The hidden file input always holds the files on screen, so name submits them with a native form, required blocks an empty one, and a form reset puts back the starting files. A file drag is always taken, even a rejected one, so the browser never opens the file in place of the page. Five sizes on the control scale, outline, soft and subtle frames, Field wiring, and slots for every part, including triggerAttrs for your own button.

    93e57a0 — Every size on the control scale is named xs to xl; default and the bare icon are gone. To move over:

    - Button: size="default" becomes size="md", or leave size out; size="icon" becomes size="icon-md". The full set is xs to xl and icon-xs to icon-xl. Toggle, ToggleGroup, ToggleGroupItem, the Toolbar parts, AlertDialogAction, AlertDialogCancel and ToastAction take the same names; Button, Toggle and ToggleGroup default to md, the Toolbar parts keep sm and ToastAction keeps xs. InputGroupButton keeps its own xs, sm, icon-xs and icon-sm, 24 and 32px to fit inside the group, xs by default. Pagination hands its md to Button as it is. Button, Toggle and ToggleGroupItem set data-variant, data-color and data-size even when you leave them at their defaults. - AlertDialogContent: size="default" becomes size="md", still the default; sm is unchanged. The size option of useConfirm's confirm, alert and prompt takes the same names. - Table and DataTable: density becomes size, data-density becomes data-size, and the TableDensity type is now TableSize. sm, md and lg keep their 36, 44 and 52px rows; xs (28px) and xl (60px) are new, and DataTable's virtual row estimates cover them. The cells' padding above and below the text is now --table-cell-py on the table: 8px as before, 3px at xs. At xs, DataTable's sort buttons and expand and group toggles shrink to fit the row. The table-density example is now table-sizes. - DrawerMenu: size takes xs to xl like Menu and reads the control scale, plus room for a thumb. sm, md and lg keep their 40, 48 and 56px rows, padding and icons; xs is 36px and xl 64px. Overriding a --control-* token on :root now resizes DrawerMenu rows as well. - Select and Combobox: the list opens at the trigger's or anchor's size instead of always at md, so <SelectTrigger size="xl"> opens an xl list. size on SelectContent or ComboboxList picks another. Behind an as-child button, set size on ComboboxAnchor to match the button. The Select list now sets its menu variables on SelectContent instead of its viewport, so a class such as [--menu-item-height:2.5rem] on SelectContent reaches the items. - Input, Textarea, InputFloating, SelectTrigger, ComboboxAnchor and Separator set data-size with the default filled in, and the anchor sets data-variant too. With as-child, the anchor leaves the button's own data-variant and data-size alone.

  6. registry 0.12.0

    c79028b — The control scale is now a set of tokens: --control-height-*, --control-padding-*, --control-icon-* and --control-gap-* for xs to xl, added to :root by the tokens item. Button, Input, InputFloating, Select, Combobox, InputNumber, TagsInput, PinInput, InputTime, InputGroup, Menu, Tabs, ColorPicker and Pagination read them, so overriding one on :root resizes every control of that size.

    Some sizes that strayed from the scale now follow it. Button icons are 20px at lg and xl instead of 16px, and so are the icons of Toggle, ToggleGroup, Toolbar and Pagination at those sizes. The gap between an icon and its label is 6, 8, 8, 10 and 12px from xs to xl, about half the icon, everywhere that has one: Button and the components built on it (where it was 4, 6, 8, 8 and 8px), Menu items and the Select, Combobox and Command lists (8, 10, 12, 12 and 12px), and Tabs triggers (6, 8, 8, 8 and 10px). Inset and checkbox or radio items move their labels with it, so they stay in line with items that have an icon. Everything else keeps its size.

  7. registry 0.9.0

    f3e1bd4 — New AlertDialog: shadcn's parts over Reka UI's AlertDialog on Dialog's window and overlay, with AlertDialogMedia, a sm size, and AlertDialogAction / AlertDialogCancel that take Button's variant, color and size. New confirm item: useConfirm() returns confirm, alert and prompt, which open alert dialogs from code and resolve with a DialogResult; onConfirm holds the dialog with a spinner while it runs and keeps it open if it throws, and prompt validates its value.

    99c55af — Components size their icons with core's icon-size-* instead of [&_svg:not([class*='size-'])]:size-*, so class="icon-size-5" resizes the icons in a Button, a Badge or a menu item, and cn lets the later of two icon-size-* classes win. A Button tightens its padding beside a data-icon="inline-start" or "inline-end" icon on the logical side, so the right side in right-to-left text.

  8. registry 0.8.0

    0f257de — Card: outline and subtle draw their edge as a one-pixel ring outside the box instead of a border, so every variant has the same size, as Button's do, and content that reaches the sides, a flush image or a list of items, never covers it.

    a2a4d38 — Button and Alert: the outline variant no longer paints bg-background, so an outline button or alert on a tinted surface shows the surface through it, as Badge's outline already did.

  9. registry 0.7.0

    07109fb — Toolbar: Toolbar, ToolbarButton, ToolbarLink, ToolbarSeparator, ToolbarToggleGroup and ToolbarToggleItem over Reka UI's toolbar, drawn with Button and ToggleGroup: one tab stop, arrow-key focus, a framed outline or a bare ghost variant.

  10. registry 0.6.0

    715f6fc — Components are coloured by tones. A colour is three inputs, --tone, --tone-foreground and --tone-text, set on [data-slot][data-color="<name>"]; core derives --tone-soft, --tone-soft-foreground, --tone-border and --tone-border-subtle from them and registers all seven as tone-* colours, so bg-tone, text-tone-text and the rest work as classes. The --c-* variables are gone: a rule that set --c, --c-fg, --c-soft, --c-soft-fg or --c-edge now sets --tone, --tone-foreground and --tone-text, and drops the rest. Button, Badge, Alert, Toggle, the choice controls and Toast read tones; Toast no longer exports toastAccents.

  11. core 0.5.0

    715f6fc — Components are coloured by tones. A colour is three inputs, --tone, --tone-foreground and --tone-text, set on [data-slot][data-color="<name>"]; core derives --tone-soft, --tone-soft-foreground, --tone-border and --tone-border-subtle from them and registers all seven as tone-* colours, so bg-tone, text-tone-text and the rest work as classes. The --c-* variables are gone: a rule that set --c, --c-fg, --c-soft, --c-soft-fg or --c-edge now sets --tone, --tone-foreground and --tone-text, and drops the rest. Button, Badge, Alert, Toggle, the choice controls and Toast read tones; Toast no longer exports toastAccents.

  12. registry 0.5.0

    86397f1 — Add MenuTrigger: a Reka-shaped part that marks the element opening a Menu placed next to it, so <MenuTrigger as-child><Button /></MenuTrigger><Menu /> reads like a dropdown menu. A Menu with the default target prefers a sibling trigger over the element it is placed in.

    d290041 — Add Toggle and ToggleGroup. Toggle is a two-state button with Button's variants, colours and sizes, styled when on by activeVariant and activeColor; ToggleGroup joins toggles like a ButtonGroup, with single or multiple selection and arrow-key navigation. The core colour rules also match [data-state="on"][data-active-color], so an on toggle reads its active colour.

    59f9254 — Add Tooltip, from shadcn-vue, with its behaviour in @kappa-ui/core/tooltip: it opens once the pointer rests on the trigger (moving restarts the wait), on keyboard focus only, and on a long press on touch screens; tooltips under a TooltipProvider warm up together; update:open reports why it opened or closed; role="label" suits icon buttons; followCursor keeps it at the pointer. v-tooltip gives the same tooltip from a string or an options object, with the side as its argument and .label for icon buttons. Button with aria-disabled="true" now looks disabled while keeping focus and pointer events, and swallows its click. A Kbd inside a tooltip takes the tooltip's colours.

  13. core 0.4.0

    d290041 — Add Toggle and ToggleGroup. Toggle is a two-state button with Button's variants, colours and sizes, styled when on by activeVariant and activeColor; ToggleGroup joins toggles like a ButtonGroup, with single or multiple selection and arrow-key navigation. The core colour rules also match [data-state="on"][data-active-color], so an on toggle reads its active colour.

    59f9254 — Add Tooltip, from shadcn-vue, with its behaviour in @kappa-ui/core/tooltip: it opens once the pointer rests on the trigger (moving restarts the wait), on keyboard focus only, and on a long press on touch screens; tooltips under a TooltipProvider warm up together; update:open reports why it opened or closed; role="label" suits icon buttons; followCursor keeps it at the pointer. v-tooltip gives the same tooltip from a string or an options object, with the side as its argument and .label for icon buttons. Button with aria-disabled="true" now looks disabled while keeping focus and pointer events, and swallows its click. A Kbd inside a tooltip takes the tooltip's colours.

  14. registry 0.3.0

    311dead — Add Alert: Alert, AlertTitle, AlertDescription and AlertActions, with Button's variants and colours, five sizes and two orientations.

    e58b25a — Add an info colour: --info, --info-foreground and --info-text tokens, data-color="info", and info on Button, Badge and toasts.

  15. core 0.3.0

    e58b25a — Add an info colour: --info, --info-foreground and --info-text tokens, data-color="info", and info on Button, Badge and toasts.

  16. registry 0.2.0

    c935598 — Colour and variant are separate axes: [data-slot][data-color] rules in @kappa-ui/core/tailwind.css set --c-* variables that Button and Badge variants read, so a custom colour is one CSS rule plus color="<name>". Core gains the touch-target, touch-target-margin, touch-target-wrapper, state-halo, choice-row, slider-axis, slider-touch and slider-range-inset utilities and the scrollbar-gutter base rule. The choice-group, text-control, menu-styles and overlay registry items are gone: their styles now live in checkbox, input, menu and popover.

  17. core 0.2.0

    c935598 — Colour and variant are separate axes: [data-slot][data-color] rules in @kappa-ui/core/tailwind.css set --c-* variables that Button and Badge variants read, so a custom colour is one CSS rule plus color="<name>". Core gains the touch-target, touch-target-margin, touch-target-wrapper, state-halo, choice-row, slider-axis, slider-touch and slider-range-inset utilities and the scrollbar-gutter base rule. The choice-group, text-control, menu-styles and overlay registry items are gone: their styles now live in checkbox, input, menu and popover.