Button component

Playground

Change a prop on the right and the preview updates. Switch to Code to copy what you see.

Recipes

Copy-paste patterns for the ways Button actually gets used — each one a real, self-contained example.

<Button>Solid</Button>
<Button variant="soft">Soft</Button>
<Button variant="bordered">Bordered</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>

<Button color="primary">Primary</Button>
<Button color="success">Success</Button>
<Button color="warning">Warning</Button>
<Button color="danger">Delete</Button>

<Button size="xs">Extra small</Button>
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>
<Button size="xl">Extra large</Button>

<Button startContent={<PlusIcon />}>New item</Button>
<Button variant="bordered" endContent={<ArrowRightIcon />}>
  Continue
</Button>

<Button isIconOnly aria-label="Add">
  <PlusIcon />
</Button>
<Button isIconOnly variant="bordered" aria-label="Download">
  <DownloadIcon />
</Button>

<Button isLoading>Saving…</Button>
<Button isLoading variant="bordered" spinnerPlacement="end">
  Processing
</Button>

<div className="max-w-sm">
  <Button fullWidth color="primary">Create account</Button>
</div>

import Link from "next/link";

<Button as={Link} href="/docs/installation">Get started</Button>

Variant and color

variant sets how much visual weight a button carries: solid (the default) is a filled, high-contrast action; soft is a tinted background for secondary actions that shouldn't compete with a solid primary button nearby; bordered keeps just an outline; ghost has no background or border until hovered; link strips button chrome entirely and reads as an inline text link. color is one of seven semantic roles and works the same way across every variant.

<Button variant="solid" color="primary">Save</Button>
<Button variant="soft" color="default">Cancel</Button>
<Button variant="bordered" color="danger">Delete</Button>
<Button variant="ghost" color="default">Skip</Button>
<Button variant="link" color="primary">Learn more</Button>

Rendering as a link

Pass href and Button renders a real anchor instead of a button element — no wrapping a Button inside a Link and fighting duplicate focus rings. target/rel/download all forward straight to the anchor, and rel defaults to "noopener noreferrer" automatically whenever target="_blank" is set, so external links can't be quietly forgotten. For a client-side router's own Link component, use the polymorphic as prop instead.

<Button href="/pricing" variant="soft">View pricing</Button>
<Button href="https://github.com/oks-ui" target="_blank">GitHub ↗</Button>

// Polymorphic: render as next/link (or any component) instead of <a>/<button>
<Button as={Link} href="/dashboard" color="primary">
  Go to dashboard
</Button>

Loading and disabled states

isLoading swaps in a spinner (spinnerPlacement controls which side of the label it sits on, or pass your own spinner node) and sets aria-busy — but the button stays focusable and enabled on purpose, so a screen reader user tabbed onto it doesn't lose their place mid-action. Use isDisabled separately when the action genuinely shouldn't be reachable at all; disabling removes it from the tab order and, on an anchor-rendered button, adds aria-disabled since native <a> has no disabled attribute.

<Button isLoading color="primary">Saving…</Button>
<Button isDisabled variant="soft">Unavailable</Button>

Icon-only buttons

For a button that's just an icon, set isIconOnly (which switches to a square footprint sized off the current size scale) and always pass an aria-label — there's no visible text for assistive tech to fall back on otherwise.

<Button isIconOnly variant="ghost" aria-label="Close">
  <XIcon />
</Button>

Press events, not just onClick

Button forwards native onClick as usual, but also exposes onPress/onPressStart/onPressEnd/onPressUp/onPressChange for cases that care about the full press lifecycle (press-and-hold interactions, custom ripple-adjacent effects, distinguishing a press that started on the button but was dragged off before release). Reach for plain onClick unless you specifically need one of those finer-grained moments.

Props

The full public API for Button. Every prop is stable and intentionally typed.

Accessibility

• •Renders semantic <button type="button"> or <a> — never a styled <div> — so it's keyboard-operable and correctly announced without any extra ARIA wiring.
• •isLoading sets aria-busy="true" but deliberately leaves the button enabled and focusable, since disabling it mid-action would silently drop focus for a keyboard/screen-reader user.
• •isDisabled sets the native disabled attribute on a <button>, or aria-disabled + tabIndex={-1} when rendered as an anchor (href set), since <a> has no native disabled state.
• •isIconOnly buttons have no visible label — always pass your own aria-label so the control has an accessible name.

Best practices

• ◆Reserve variant="solid" for the one primary action in a given area — a screen with five solid buttons gives the eye nothing to anchor on.
• ◆Prefer isLoading over swapping the button out for a spinner entirely; keeping the button in place (just busy) avoids a layout shift and a lost focus target.
• ◆Use href (or as) instead of wrapping Button in a separate anchor/Link — the polymorphic behavior exists specifically so you never end up with two nested interactive elements.
• ◆Always pair isIconOnly with aria-label; if the icon also has a visible tooltip, the label should still describe the action on its own since tooltips aren't reliably read by every assistive technology.
• ◆For a set of related actions that should look like one connected control (Prev/Next, view toggles), use ButtonGroup instead of manually managing spacing and border-radius between adjacent Buttons.