# Button

Displays a button or a component that behaves like a button.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="button" />

<ComponentPreview name="button" title="button.tsx">
<Component />
</ComponentPreview>

Buttons trigger an action or event when clicked. They communicate intent through a compact surface, an icon, and a short label.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add button
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install class-variance-authority
```

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="button" title="components/ui/button.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="button.tsx"
import { Button } from "@/components/ui/button";
```

```tsx title="button.tsx"
<Button>Click me</Button>
```

## Variants [#variants]

| Variant | Use case |
| :-- | :-- |
| `default` | Primary action |
| `secondary` | Secondary action |
| `outline` | Bordered neutral |
| `ghost` | Minimal, hover only |
| `destructive` | Irreversible action |
| `link` | Inline link styling |

Set with the `variant` prop:

```tsx
<Button variant="outline">Cancel</Button>
```

### Default [#default]

The primary variant, intended for the most important action on a page.

<ComponentPreview name="button-default" title="button-default.tsx" src="examples/button-default.tsx">
<a />
</ComponentPreview>

### Secondary [#secondary]

Intended for actions of lesser prominence.

<ComponentPreview name="button-secondary" title="button-secondary.tsx" src="examples/button-secondary.tsx">
<l />
</ComponentPreview>

### Outline [#outline]

Renders with a border and a transparent background.

<ComponentPreview name="button-outline" title="button-outline.tsx" src="examples/button-outline.tsx">
<r />
</ComponentPreview>

### Ghost [#ghost]

Renders without a border. Background applies only on hover.

<ComponentPreview name="button-ghost" title="button-ghost.tsx" src="examples/button-ghost.tsx">
<h />
</ComponentPreview>

### Destructive [#destructive]

Intended for destructive or irreversible actions.

<ComponentPreview name="button-destructive" title="button-destructive.tsx" src="examples/button-destructive.tsx">
<d />
</ComponentPreview>

### Link [#link]

Renders as inline text with an underline on hover.

<ComponentPreview name="button-link" title="button-link.tsx" src="examples/button-link.tsx">
<o />
</ComponentPreview>

### Custom radius [#custom-radius]

<ComponentPreview name="button-rounded" title="button-rounded.tsx" src="examples/button-rounded.tsx">
<b />
</ComponentPreview>

## Size & Icon Size [#size--icon-size]

Use the `size` prop to control the dimensions of a text button.

<ComponentPreview name="button-size" title="button-size.tsx" src="examples/button-size.tsx">
<p />
</ComponentPreview>

| Size      | Height | Padding |
| :-------- | :----- | :------ |
| `xs`      | 28px   | `px-2`  |
| `sm`      | 32px   | `px-3`  |
| `default` | 36px   | `px-4`  |
| `lg`      | 40px   | `px-6`  |

Icon sizes use the same `size` prop. Pass `size="icon-xs"`, `"icon-sm"`, `"icon"`, or `"icon-lg"` for a square button that fits a single icon.

| Size      | Dimensions |
| :-------- | :--------- |
| `icon-xs` | 28×28      |
| `icon-sm` | 32×32      |
| `icon`    | 36×36      |
| `icon-lg` | 40×40      |

## Icons & With Icons [#icons--with-icons]

Buttons accept an icon next to a label or render as a square icon-only button. Icons are sized to 16px by `[&_svg]:size-4`.

<ComponentPreview name="button-icons-combo" title="button-icons-combo.tsx" src="examples/button-icons-combo.tsx">
<j />
</ComponentPreview>

## Motion [#motion]

By default the button uses Tailwind's `transition-all` (150ms, `ease-in-out`). Pass `motion` to override the transition without editing the file.

### Default [#default-1]

<ComponentPreview name="button-motion-default" src="examples/button-motion-default.tsx" title="button-motion-default.tsx">
<v />
</ComponentPreview>

### Reduced motion [#reduced-motion]

`prefers-reduced-motion: reduce` disables the transition automatically. The first button below opts out with `className="transition-none"`. The second uses the default and respects the OS setting.

<ComponentPreview name="button-motion-reduced" src="examples/button-motion-reduced.tsx" title="button-motion-reduced.tsx">
<B />
</ComponentPreview>

### Value reference [#value-reference]

| Value | Result |
| :-- | :-- |
| omitted | Tailwind `transition-all` (150ms ease-in-out) |
| `"150"` | 150ms ease-in-out |
| `"200 cubic-bezier(0.16, 1, 0.3, 1)"` | 200ms custom easing |

```tsx
<Button motion="300 ease-out">Slow reveal</Button>
```

To remove the default transition without a motion value, pass `className="transition-none"`. This is not a `motion` prop value — it is a Tailwind utility that wins over the base class.

### Using your own animation library [#using-your-own-animation-library]

Attach GSAP, Framer Motion, the Web Animations API, or any library that writes inline styles to the element. The component detects the first external write and disables its own CSS transition automatically. No extra prop is required.

```tsx
const ref = useRef<HTMLButtonElement>(null);

useEffect(() => {
  gsap.to(ref.current, { scale: 1.1, duration: 0.3 });
}, []);

<Button ref={ref}>Animated by GSAP</Button>
```

CSS class changes such as hover styles do not trigger the guard. Only inline style writes from a library or a manual ref assignment do.

## Loading State [#loading-state]

Render a spinner beside the label and set `disabled` to indicate an in-progress action.

<ComponentPreview name="button-loading" title="button-loading.tsx" src="examples/button-loading.tsx">
<f />
</ComponentPreview>

## Links & Router links [#links--router-links]

A button can navigate. Use `href` for a static anchor, or `as` to render a router link. The first button below is a static `<a>`; the second is a Next.js `<Link>` rendered with button styles.

<ComponentPreview name="button-anchor" title="button-anchor.tsx" src="examples/button-anchor.tsx">
<ButtonAnchor />
</ComponentPreview>

Static link:

```tsx
import { Button } from "@/components/ui/button";

<Button href="/pricing" variant="outline">Pricing</Button>
```

Router link:

```tsx
import Link from "next/link";
import { Button } from "@/components/ui/button";

<Button as={Link} href="/pricing" variant="outline">Pricing</Button>
```

Custom component:

```tsx
<Button as={MyLink} to="/pricing" variant="outline">Pricing</Button>
```

### Which approach to pick [#which-approach-to-pick]

| Case | Approach |
| --- | --- |
| Static site, plain HTML, external URL | `<Button href="...">` |
| Next.js, React Router, TanStack Router | `<Button as={Link} href="...">` |
| Custom component with its own props | `<Button as={CustomComponent}>` |
| Triggers an action, not navigation | `<Button onClick={...}>` |

## Button Group [#button-group]

For grouped actions, see [Button Group](/docs/components/button-group). A quick example:

<ComponentPreview name="button-group-demo" title="button-group-demo.tsx" src="examples/button-group-demo.tsx">
<ButtonGroupDemo />
</ComponentPreview>

## API Reference [#api-reference]

### Button [#button]

<PropsTable />

### buttonVariants [#buttonvariants]

The `buttonVariants` helper returns the class string for any variant and size. Use it to apply button styles to a router link component.

```tsx
import { buttonVariants } from "@/lib/utils";

<a className={buttonVariants({ variant: "outline", size: "sm" })} href="/docs">
  Read the docs
</a>
```

<PropsTable rows={[{"name":"variant","type":"default | secondary | outline | ghost | destructive | link","description":"The visual style."},{"name":"size","type":"xs | sm | default | lg | icon-xs | icon-sm | icon | icon-lg","description":"The dimensions."},{"name":"className","type":"string","description":"Additional classes merged with cn()."}]} />

## Accessibility [#accessibility]

- Set `type="button"` on buttons that are not intended to submit a form.
- Provide an `aria-label` on icon-only buttons.
- `disabled` removes the button from the tab order.
- Color contrast is maintained by design tokens. Run your own contrast check for custom tokens.

## Best Practices [#best-practices]

- **Use one primary button per surface.**
- **Prefer `size="sm"` inside toolbars.**
- **Never rely on color alone.**
- **Use `href` for static links, `as={Link}` for router links.**
- **Reserve `destructive` for irreversible actions.**

## Related Components [#related-components]

- [Button Group](/docs/components/button-group) — visually group buttons
- [Toggle](/docs/components/toggle) — two-state button
- [Input Group](/docs/components/input-group) — button inside an input