Primitives · Application UI
Button
A polymorphic button component built on Base UI with CVA-powered variant and size styles, supporting icon-only sizes and custom render targets.
Feature showcase
Installation
Features
CVA-powered variants and sizes
Covers emphasis, destructive, link, compact, large, and icon-only button shapes.
Polymorphic render target
Can render as links or custom elements while preserving Base UI button semantics.
Built-in status affordances
Supports loading and error states through data attributes and internal status rendering.
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "default" | "outline" | "secondary" | "ghost" | "destructive" | "link" | "default" | Visual style of the button. |
| size | "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | "default" | Controls height, padding, and icon sizing. |
| render | React.ReactElement | ((props: object) => React.ReactElement) | - | Swap the underlying element (e.g. a Next.js Link); nativeButton is inferred automatically. |
| nativeButton | boolean | - | Override Base UI's native-button semantics inference when using a custom render target. |
| className | string | - | Additional Tailwind classes merged onto the variant styles. |
| disabled | boolean | - | Disables pointer events and reduces opacity via the disabled: utilities. |
Exports
| Export | Kind | Description |
|---|---|---|
| Button | component | Polymorphic Base UI button primitive. |
| buttonVariants | constant | CVA variant helper for button styles. |
| ButtonProps | type | Public props for the Button component. |
| ButtonStatus | type | Status values used for loading and error affordances. |
Slots
| Slot | Element | Description |
|---|---|---|
| button | button | Root interactive element or custom render target. |
| button-spinner | span | Loading indicator slot rendered inside the button. |
Source and related
| File | Path |
|---|---|
| Component | registry/ui/button.tsx |
| Default example | content/examples/button/default.tsx |
| Variants example | content/examples/button/variants.tsx |