Button

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add button

Usage#

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

export function Example() {
  return <Button>Click me</Button>
}

Split button#

Keep the main action visible and put its alternatives in the attached menu. The two segments stay independent: clicking the label runs the primary action, while the caret opens the menu.

Playground#

Every knob here is a prop, because a Button is one element with nothing to compose. variant, size and iconOnly are read straight off the component’s own recipe, so they can never drift from it.

<Button>Continue</Button>

Variants#

primary carries the brand and is the one action a screen leads with. neutral is the achromatic solid: an ink fill with the page ground as its label, black on the light themes and near-white on the dark ones. Reach for it when a strong action shares the screen with a brand CTA and must not compete with it ("See all components" under a brand "Buy now"), where secondary would be too quiet.

On a filled band#

A button sitting on a color band or over a photo has the wrong ground: the brand fill of a primary action disappears into a brand band, and accent hovers resolve against the page, not the band. tone says which ground it is on, and every variant answers for itself.

onMedia is a fixed white family, for a brand band, a photo, or a dark scrim. The lead action becomes a white chip and the second stays a white outline, which is how GOV.UK, Spectrum and Tailwind Plus handle a colored band. The chip's label is near-black ink, never the brand color: the band already carries the accent, and black on white clears AA on every accent. onInverse is its token-flipping twin, for a bg-foreground band: that band inverts with the theme, so the button inverts with it. Both also re-point the focus ring, which is otherwise an invisible brand halo on a brand fill - so reach for the prop rather than a className, which would fix the fill and leave the ring broken.

Over a picture#

tone="onMedia" trusts the ground to be dark or saturated. An action placed straight on a picture can't: a thumbnail's corner button may land on a white frame as easily as on a dark one, and a white ghost glyph vanishes there. variant="overlay" brings its own ground, a dark translucent chip with a faint white edge (the same recipe as Badge's overlay), so it reads over any frame. Its focus ring is white on a transparent offset, like the on-media tones.

Sizes#

Three control sizes on a 4px grid - sm (32px), md (36px, the default), and lg (40px). The label stays text-sm across them; only height, padding, and the icon gap step up - so a larger button reads as the same control with more presence, not bigger text. Then xl (44px), the marketing CTA tier: the one step where the label grows to 16px and a glyph to 20px, because beside a 60-72px display title a 14px label reads as fine print. It is button-only (no form wants a 44px field), and a hero's CTA row imposes it by default. At the other end, xs (28px) is the dense-UI tier, covered below.

Extra small, for dense UI

xs is 28px tall: a table row's actions, the close on a floating card, a toolbar packed into a panel. The label drops to text-xs and a glyph to 14px so both keep their proportion to the smaller box, and with iconOnly it is a 28 by 28 square. The visual shrinks, the target does not: an invisible pseudo-element keeps the hit area at 40px (44px on touch), the same extender sm uses. Like xl it is button-only; a field under a container that imposes it resolves it to sm. It works with every variant and tone, and on a ButtonGroup.

Density#

Height always comes from size, never from density. The default button is md (36px) everywhere: a compact dashboard under DensityProvider and a comfortable landing render the same unsized button, so the product has one default. A density prop on the button itself still picks its default (the two below: comfortable md, compact sm), and a container that imposes a tier (InputGroup, a data-table toolbar, Form, hero actions) keeps its buttons level with the fields beside them. An explicit size always wins; a pseudo-element holds xs and sm at a hit target of ≥40px. See Density.

Icons#

Icons are composed as children, not props - the recipe sizes any svg to size-4 and a gap spaces it from the label. Put the icon before or after the text to place it left or right. A button carrying an icon trims its horizontal padding one step (has-[>svg]:px-*) - an icon reads lighter than a text edge, so this keeps it optically balanced. For an icon-only button set iconOnly - it collapses to a square at any size - and always pass an aria-label, since there is no visible text. Koala warns in development if an iconOnly button has no accessible name.

Left or right: a UX rule

Placement is not decorative. In left-to-right reading the eye lands on the start of the button and leaves at the end, so each side has a different job: a leading icon identifies the action, a trailing icon signals where it goes.

One nuance overrides the default: keep the icon on the side that matches its meaning. A back-arrow belongs on the left because it points the way the action travels, even though most icons lead. When unsure, lead with the icon.

Its own tooltip

An iconOnly button shows its aria-label (or tooltip) as a hint on hover and keyboard focus. tooltip={false} turns it off. Wrap the button in your own Tooltip, directly or through an asChild trigger like PopoverTrigger, and the built-in hint stands down: one bubble, the one you wrote.

<Tooltip content={<>Search <Kbd size="sm">⌘K</Kbd></>}>
  <Button iconOnly aria-label="Search">
    <MagnifyingGlass />
  </Button>
</Tooltip>

Attached to the label, not the edge

The icon rides directly beside the label, and the pair centers together as one unit. This matters most on full-width buttons - form submits, social sign-in, mobile CTAs - where pinning the icon to the button's edge opens a gap that strands the mark away from the text it belongs to.

Social buttons#

SocialButton is a sign-in button carrying a real brand logo - the authentic marks, not icon-style approximations. It wraps Button, so every size, density, the press scale, loading, and the icon-only tooltip all carry over. Pass a provider and it supplies the logo and the default Continue with… label.

Solid

appearance="solid" fills the button with the provider's official color and flattens the logo to white - for a single dominant choice or a brand-forward row.

Icon only

Set iconOnly for a square logo button - the provider name becomes the aria-label and the hover tooltip. Every supported provider:

Disabled#

Loading#

loading shows a spinner and marks the button busy (aria-busy) while an action is in flight. The label is hidden but its space is reserved, so the button never reflows; it's also disabled so it can't be re-triggered. The spinner respects prefers-reduced-motion.

Label swap#

When a button's label changes with its state - Next → Done, Copy → Copied, Follow → Following - give it a swapKey that changes with it. The outgoing label lifts up and out while the new one rises from below, and the button eases between the two label widths instead of snapping to the new one. It respects prefers-reduced-motion, where the label simply swaps.

As child#

Use asChild to render the button styles on a different element - e.g. a Next.js Link - via Radix Slot, with no extra wrapper.

API reference#

FAQ#