- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
"use client";
import type { VariantProps } from "class-variance-authority";
import * as React from "react";
import {
getTransition,
parseMotion,
useMotionGuard,
useReducedMotion,
} from "@/lib/motion";
import { buttonVariants, cn } from "@/lib/utils";
export interface ButtonBaseProps extends VariantProps<typeof buttonVariants> {
anchorRef?: React.Ref<HTMLAnchorElement>;
as?: React.ElementType;
children?: React.ReactNode;
className?: string;
download?: string | boolean;
href?: string;
motion?: string;
rel?: string;
target?: React.HTMLAttributeAnchorTarget;
}
// biome-ignore lint/suspicious/noExplicitAny: loose polymorphic props for the `as` escape hatch
export type ButtonProps = ButtonBaseProps & Record<string, any>;
function Button({
as,
className,
variant,
size,
href,
target,
rel,
download,
ref,
anchorRef,
motion,
style,
children,
...props
}: ButtonProps) {
const reduce = useReducedMotion();
const internalRef = React.useRef<HTMLElement | null>(null);
const motionEnabled = motion !== undefined && !reduce;
let resolvedStyle = style as React.CSSProperties | undefined;
if (reduce) {
resolvedStyle = { ...resolvedStyle, transition: "none" };
} else if (motion !== undefined) {
const transition = getTransition(parseMotion(motion));
if (transition) {
resolvedStyle = { ...resolvedStyle, transition };
}
}
const styleFingerprint = JSON.stringify(resolvedStyle ?? null);
const yielded = useMotionGuard(internalRef, motionEnabled, styleFingerprint);
if (yielded && !reduce) {
resolvedStyle = { ...resolvedStyle, transition: "none" };
}
const setRef = React.useCallback(
(el: HTMLElement | null) => {
internalRef.current = el;
if (href !== undefined && anchorRef) {
if (typeof anchorRef === "function") {
anchorRef(el as HTMLAnchorElement | null);
} else {
(
anchorRef as React.MutableRefObject<HTMLAnchorElement | null>
).current = el as HTMLAnchorElement | null;
}
}
if (typeof ref === "function") {
(ref as (el: HTMLElement | null) => void)(el);
} else if (ref && typeof ref === "object") {
(ref as React.MutableRefObject<HTMLElement | null>).current = el;
}
},
[href, ref, anchorRef]
);
const classes = cn(buttonVariants({ className, size, variant }));
const attrs = {
"data-inline": true,
"data-size": size,
"data-slot": "button",
"data-variant": variant,
} as const;
if (as !== undefined) {
const allProps: Record<string, unknown> = {
...attrs,
...props,
className: classes,
ref: setRef,
style: resolvedStyle,
};
if (href !== undefined) {
allProps.href = href;
}
if (download !== undefined) {
allProps.download = download;
}
if (rel !== undefined) {
allProps.rel = rel;
}
if (target !== undefined) {
allProps.target = target;
}
return React.createElement(as, allProps, children);
}
if (href !== undefined) {
const {
type: _t,
disabled: _d,
form: _f,
formAction: _fa,
formEncType: _fe,
formMethod: _fm,
formNoValidate: _fnv,
formTarget: _ft,
name: _n,
value: _v,
...anchorRest
} = props as React.ButtonHTMLAttributes<HTMLButtonElement>;
return (
<a
className={classes}
download={download}
href={href}
ref={setRef}
rel={rel}
style={resolvedStyle}
target={target}
{...attrs}
{...(anchorRest as React.AnchorHTMLAttributes<HTMLAnchorElement>)}
>
{children}
</a>
);
}
return (
<button
className={classes}
ref={setRef}
style={resolvedStyle}
{...attrs}
{...(props as React.ButtonHTMLAttributes<HTMLButtonElement>)}
>
{children}
</button>
);
}
export { Button };Buttons trigger an action or event when clicked. They communicate intent through a compact surface, an icon, and a short label.
Installation
$ bunx --bun frakment add button$ npx frakment add button$ pnpm dlx frakment add button$ yarn dlx frakment add button
Install the following dependencies:
$ bun add class-variance-authority$ npm install class-variance-authority$ pnpm add class-variance-authority$ yarn add class-variance-authority
Copy and paste the following code into your project.
"use client";
import type { VariantProps } from "class-variance-authority";
import * as React from "react";
import {
getTransition,
parseMotion,
useMotionGuard,
useReducedMotion,
} from "@/lib/motion";
import { buttonVariants, cn } from "@/lib/utils";
export interface ButtonBaseProps extends VariantProps<typeof buttonVariants> {
anchorRef?: React.Ref<HTMLAnchorElement>;
as?: React.ElementType;
children?: React.ReactNode;
className?: string;
download?: string | boolean;
href?: string;
motion?: string;
rel?: string;
target?: React.HTMLAttributeAnchorTarget;
}
// biome-ignore lint/suspicious/noExplicitAny: loose polymorphic props for the `as` escape hatch
export type ButtonProps = ButtonBaseProps & Record<string, any>;
function Button({
as,
className,
variant,
size,
href,
target,
rel,
download,
ref,
anchorRef,
motion,
style,
children,
...props
}: ButtonProps) {
const reduce = useReducedMotion();
const internalRef = React.useRef<HTMLElement | null>(null);
const motionEnabled = motion !== undefined && !reduce;
let resolvedStyle = style as React.CSSProperties | undefined;
if (reduce) {
resolvedStyle = { ...resolvedStyle, transition: "none" };
} else if (motion !== undefined) {
const transition = getTransition(parseMotion(motion));
if (transition) {
resolvedStyle = { ...resolvedStyle, transition };
}
}
const styleFingerprint = JSON.stringify(resolvedStyle ?? null);
const yielded = useMotionGuard(internalRef, motionEnabled, styleFingerprint);
if (yielded && !reduce) {
resolvedStyle = { ...resolvedStyle, transition: "none" };
}
const setRef = React.useCallback(
(el: HTMLElement | null) => {
internalRef.current = el;
if (href !== undefined && anchorRef) {
if (typeof anchorRef === "function") {
anchorRef(el as HTMLAnchorElement | null);
} else {
(
anchorRef as React.MutableRefObject<HTMLAnchorElement | null>
).current = el as HTMLAnchorElement | null;
}
}
if (typeof ref === "function") {
(ref as (el: HTMLElement | null) => void)(el);
} else if (ref && typeof ref === "object") {
(ref as React.MutableRefObject<HTMLElement | null>).current = el;
}
},
[href, ref, anchorRef]
);
const classes = cn(buttonVariants({ className, size, variant }));
const attrs = {
"data-inline": true,
"data-size": size,
"data-slot": "button",
"data-variant": variant,
} as const;
if (as !== undefined) {
const allProps: Record<string, unknown> = {
...attrs,
...props,
className: classes,
ref: setRef,
style: resolvedStyle,
};
if (href !== undefined) {
allProps.href = href;
}
if (download !== undefined) {
allProps.download = download;
}
if (rel !== undefined) {
allProps.rel = rel;
}
if (target !== undefined) {
allProps.target = target;
}
return React.createElement(as, allProps, children);
}
if (href !== undefined) {
const {
type: _t,
disabled: _d,
form: _f,
formAction: _fa,
formEncType: _fe,
formMethod: _fm,
formNoValidate: _fnv,
formTarget: _ft,
name: _n,
value: _v,
...anchorRest
} = props as React.ButtonHTMLAttributes<HTMLButtonElement>;
return (
<a
className={classes}
download={download}
href={href}
ref={setRef}
rel={rel}
style={resolvedStyle}
target={target}
{...attrs}
{...(anchorRest as React.AnchorHTMLAttributes<HTMLAnchorElement>)}
>
{children}
</a>
);
}
return (
<button
className={classes}
ref={setRef}
style={resolvedStyle}
{...attrs}
{...(props as React.ButtonHTMLAttributes<HTMLButtonElement>)}
>
{children}
</button>
);
}
export { Button };Update the import paths to match your project setup.
Usage
import { Button } from "@/components/ui/button";<Button>Click me</Button>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:
<Button variant="outline">Cancel</Button>Default
The primary variant, intended for the most important action on a page.
import { Button } from "@/components/ui/button";
export function ButtonDefault() {
return <Button>Button</Button>;
}Secondary
Intended for actions of lesser prominence.
import { Button } from "@/components/ui/button";
export function ButtonSecondary() {
return <Button variant="secondary">Secondary</Button>;
}Outline
Renders with a border and a transparent background.
import { Button } from "@/components/ui/button";
export function ButtonOutline() {
return <Button variant="outline">Outline</Button>;
}Ghost
Renders without a border. Background applies only on hover.
import { Button } from "@/components/ui/button";
export function ButtonGhost() {
return <Button variant="ghost">Ghost</Button>;
}Destructive
Intended for destructive or irreversible actions.
import { Button } from "@/components/ui/button";
export function ButtonDestructive() {
return <Button variant="destructive">Destructive</Button>;
}Link
Renders as inline text with an underline on hover.
import { Button } from "@/components/ui/button";
export function ButtonLink() {
return <Button variant="link">Link</Button>;
}Custom radius
import { ArrowUpIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
export function ButtonRounded() {
return (
<div className="flex gap-2">
<Button className="rounded-full">Get Started</Button>
<Button className="rounded-full" size="icon" variant="outline">
<ArrowUpIcon />
</Button>
</div>
);
}Size & Icon Size
Use the size prop to control the dimensions of a text button.
import { ArrowUpRightIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
export function ButtonSize() {
return (
<div className="flex flex-col items-start gap-8 sm:flex-row">
<div className="flex items-start gap-2">
<Button size="xs" variant="outline">
Extra Small
</Button>
<Button aria-label="Submit" size="icon-xs" variant="outline">
<ArrowUpRightIcon />
</Button>
</div>
<div className="flex items-start gap-2">
<Button size="sm" variant="outline">
Small
</Button>
<Button aria-label="Submit" size="icon-sm" variant="outline">
<ArrowUpRightIcon />
</Button>
</div>
<div className="flex items-start gap-2">
<Button variant="outline">Default</Button>
<Button aria-label="Submit" size="icon" variant="outline">
<ArrowUpRightIcon />
</Button>
</div>
<div className="flex items-start gap-2">
<Button size="lg" variant="outline">
Large
</Button>
<Button aria-label="Submit" size="icon-lg" variant="outline">
<ArrowUpRightIcon />
</Button>
</div>
</div>
);
}| 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
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.
import { ButtonIcon } from "@/examples/button-icon";
import { ButtonWithIcon } from "@/examples/button-with-icon";
export function ButtonIconsCombo() {
return (
<div className="flex flex-wrap items-center justify-center gap-2">
<ButtonWithIcon />
<ButtonIcon />
</div>
);
}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
import { ArrowUpIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
export function ButtonMotionDefault() {
return (
<div className="flex flex-wrap items-center justify-center gap-2">
<Button variant="outline">Button</Button>
<Button aria-label="Submit" size="icon" variant="outline">
<ArrowUpIcon />
</Button>
</div>
);
}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.
import { CircleDotDashedIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
export function ButtonMotionReduced() {
return (
<div className="flex flex-wrap items-center justify-center gap-2">
<Button className="transition-none" variant="outline">
Static
</Button>
<Button aria-label="Submit" size="icon" variant="outline">
<CircleDotDashedIcon />
</Button>
</div>
);
}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 |
<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
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.
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
Render a spinner beside the label and set disabled to indicate an in-progress action.
import { Button } from "@/components/ui/button";
import { Spinner } from "@/components/ui/spinner";
export function ButtonLoading() {
return (
<div className="flex gap-2">
<Button disabled variant="outline">
<Spinner data-icon="inline-start" />
Generating
</Button>
<Button disabled variant="outline">
<Spinner data-icon="inline-start" />
Downloading
</Button>
</div>
);
}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.
"use client";
import Link from "next/link";
import { Button } from "@/components/ui/button";
export function ButtonAnchor() {
return (
<div className="flex flex-wrap items-center gap-2">
<Button href="/docs" variant="secondary">
Static link
</Button>
<Button as={Link} href="/docs/components/button" variant="outline">
Router link
</Button>
</div>
);
}Static link:
import { Button } from "@/components/ui/button";
<Button href="/pricing" variant="outline">Pricing</Button>Router link:
import Link from "next/link";
import { Button } from "@/components/ui/button";
<Button as={Link} href="/pricing" variant="outline">Pricing</Button>Custom component:
<Button as={MyLink} to="/pricing" variant="outline">Pricing</Button>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
For grouped actions, see Button Group. A quick example:
"use client";
import {
ArchiveIcon,
ArrowLeftIcon,
CalendarPlusIcon,
ClockIcon,
ListFilterIcon,
MailCheckIcon,
MoreHorizontalIcon,
TagIcon,
Trash2Icon,
} from "lucide-react";
import * as React from "react";
import { Button } from "@/components/ui/button";
import { ButtonGroup } from "@/components/ui/button-group";
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuGroup,
DropdownMenuItem,
DropdownMenuRadioGroup,
DropdownMenuRadioItem,
DropdownMenuSeparator,
DropdownMenuSub,
DropdownMenuSubContent,
DropdownMenuSubTrigger,
DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
export function ButtonGroupDemo() {
const [label, setLabel] = React.useState("personal");
return (
<ButtonGroup>
<ButtonGroup className="hidden sm:flex">
<Button aria-label="Go Back" size="icon" variant="outline">
<ArrowLeftIcon />
</Button>
</ButtonGroup>
<ButtonGroup>
<Button variant="outline">Archive</Button>
<Button variant="outline">Report</Button>
</ButtonGroup>
<ButtonGroup>
<Button variant="outline">Snooze</Button>
<DropdownMenu>
<DropdownMenuTrigger
aria-label="More Options"
as={Button}
size="icon"
variant="outline"
>
<MoreHorizontalIcon />
</DropdownMenuTrigger>
<DropdownMenuContent align="end" className="w-40">
<DropdownMenuGroup>
<DropdownMenuItem>
<MailCheckIcon />
Mark as Read
</DropdownMenuItem>
<DropdownMenuItem>
<ArchiveIcon />
Archive
</DropdownMenuItem>
</DropdownMenuGroup>
<DropdownMenuSeparator />
<DropdownMenuGroup>
<DropdownMenuItem>
<ClockIcon />
Snooze
</DropdownMenuItem>
<DropdownMenuItem>
<CalendarPlusIcon />
Add to Calendar
</DropdownMenuItem>
<DropdownMenuItem>
<ListFilterIcon />
Add to List
</DropdownMenuItem>
<DropdownMenuSub>
<DropdownMenuSubTrigger>
<TagIcon />
Label As...
</DropdownMenuSubTrigger>
<DropdownMenuSubContent>
<DropdownMenuRadioGroup
onValueChange={setLabel}
value={label}
>
<DropdownMenuRadioItem value="personal">
Personal
</DropdownMenuRadioItem>
<DropdownMenuRadioItem value="work">
Work
</DropdownMenuRadioItem>
<DropdownMenuRadioItem value="other">
Other
</DropdownMenuRadioItem>
</DropdownMenuRadioGroup>
</DropdownMenuSubContent>
</DropdownMenuSub>
</DropdownMenuGroup>
<DropdownMenuSeparator />
<DropdownMenuGroup>
<DropdownMenuItem variant="destructive">
<Trash2Icon />
Trash
</DropdownMenuItem>
</DropdownMenuGroup>
</DropdownMenuContent>
</DropdownMenu>
</ButtonGroup>
</ButtonGroup>
);
}API Reference
Button
| Prop | Type | Default | Description |
|---|---|---|---|
variant | defaultsecondaryoutlineghostdestructivelink | default | The visual style of the button. |
size | xssmdefaultlgicon-xsicon-smiconicon-lg | default | The dimensions of the button. |
href | string | — | Renders a native anchor with this URL instead of a button. When set, button-only props (type, disabled, form*, name, value) are ignored. |
target | string | — | Anchor target (for example, _blank). Only applies when href is set. |
rel | string | — | Anchor rel attribute. Use noopener noreferrer with target=_blank. Only applies when href is set. |
download | stringboolean | — | Prompts the browser to download the linked URL. Only applies when href is set. |
ref | Ref<HTMLButtonElement> | — | Ref to the underlying button element. Ignored when href is set. |
anchorRef | Ref<HTMLAnchorElement> | — | Ref to the underlying anchor element. Only used when href is set. |
disabled | boolean | false | Prevents interaction and applies a muted background style. Ignored when href is set. |
motion | string | — | CSS transition override. A duration like 150, 300, 300 ease-out, or a raw cubic-bezier(...). Default uses Tailwind transition-all. prefers-reduced-motion overrides every value. |
as | React.ElementType | — | Renders a different root element or component. Accepts HTML tag names or React components. Defaults to button, or a when href is set. |
onClick | function | — | Called when the button is activated. Fires on both button and anchor modes. |
type | buttonsubmitreset | submit | The native button type. Defaults to submit per HTML spec. Set to button when not submitting a form. Ignored when href is set. |
buttonVariants
The buttonVariants helper returns the class string for any variant and size. Use it to apply button styles to a router link component.
import { buttonVariants } from "@/lib/utils";
<a className={buttonVariants({ variant: "outline", size: "sm" })} href="/docs">
Read the docs
</a>| Prop | Type | Default | Description |
|---|---|---|---|
variant | defaultsecondaryoutlineghostdestructivelink | — | The visual style. |
size | xssmdefaultlgicon-xsicon-smiconicon-lg | — | The dimensions. |
className | string | — | Additional classes merged with cn(). |
Accessibility
- Set
type="button"on buttons that are not intended to submit a form. - Provide an
aria-labelon icon-only buttons. disabledremoves the button from the tab order.- Color contrast is maintained by design tokens. Run your own contrast check for custom tokens.
Best Practices
- Use one primary button per surface.
- Prefer
size="sm"inside toolbars. - Never rely on color alone.
- Use
hreffor static links,as={Link}for router links. - Reserve
destructivefor irreversible actions.
Related Components
- Button Group — visually group buttons
- Toggle — two-state button
- Input Group — button inside an input
On This Page
InstallationUsageVariantsDefaultSecondaryOutlineGhostDestructiveLinkCustom radiusSize & Icon SizeIcons & With IconsMotionDefaultReduced motionValue referenceUsing your own animation libraryLoading StateLinks & Router linksWhich approach to pickButton GroupAPI ReferenceButtonbuttonVariantsAccessibilityBest PracticesRelated Components