For the complete documentation index, see 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.
FrakmentFrakment

Button

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

WebNative
Frakment
button.tsx
"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

Usage

button.tsx
import { Button } from "@/components/ui/button";
button.tsx
<Button>Click me</Button>

Variants

VariantUse case
defaultPrimary action
secondarySecondary action
outlineBordered neutral
ghostMinimal, hover only
destructiveIrreversible action
linkInline link styling

Set with the variant prop:

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

Default

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

button-default.tsx
import { Button } from "@/components/ui/button";

export function ButtonDefault() {
  return <Button>Button</Button>;
}

Secondary

Intended for actions of lesser prominence.

button-secondary.tsx
import { Button } from "@/components/ui/button";

export function ButtonSecondary() {
  return <Button variant="secondary">Secondary</Button>;
}

Outline

Renders with a border and a transparent background.

button-outline.tsx
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.

button-ghost.tsx
import { Button } from "@/components/ui/button";

export function ButtonGhost() {
  return <Button variant="ghost">Ghost</Button>;
}

Destructive

Intended for destructive or irreversible actions.

button-destructive.tsx
import { Button } from "@/components/ui/button";

export function ButtonDestructive() {
  return <Button variant="destructive">Destructive</Button>;
}

Renders as inline text with an underline on hover.

button-link.tsx
import { Button } from "@/components/ui/button";

export function ButtonLink() {
  return <Button variant="link">Link</Button>;
}

Custom radius

button-rounded.tsx
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.

button-size.tsx
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>
  );
}
SizeHeightPadding
xs28pxpx-2
sm32pxpx-3
default36pxpx-4
lg40pxpx-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.

SizeDimensions
icon-xs28×28
icon-sm32×32
icon36×36
icon-lg40×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.

button-icons-combo.tsx
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

button-motion-default.tsx
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.

button-motion-reduced.tsx
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

ValueResult
omittedTailwind 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

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

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

button-loading.tsx
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>
  );
}

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.

button-anchor.tsx
"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:

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

CaseApproach
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:

button-group-demo.tsx
"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

PropTypeDefaultDescription
variant
defaultsecondaryoutlineghostdestructivelink
defaultThe visual style of the button.
size
xssmdefaultlgicon-xsicon-smiconicon-lg
defaultThe dimensions of the button.
hrefstring—Renders a native anchor with this URL instead of a button. When set, button-only props (type, disabled, form*, name, value) are ignored.
targetstring—Anchor target (for example, _blank). Only applies when href is set.
relstring—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.
refRef<HTMLButtonElement>—Ref to the underlying button element. Ignored when href is set.
anchorRefRef<HTMLAnchorElement>—Ref to the underlying anchor element. Only used when href is set.
disabledbooleanfalsePrevents interaction and applies a muted background style. Ignored when href is set.
motionstring—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.
asReact.ElementType—Renders a different root element or component. Accepts HTML tag names or React components. Defaults to button, or a when href is set.
onClickfunction—Called when the button is activated. Fires on both button and anchor modes.
type
buttonsubmitreset
submitThe 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.

tsx
import { buttonVariants } from "@/lib/utils";
 
<a className={buttonVariants({ variant: "outline", size: "sm" })} href="/docs">
  Read the docs
</a>
PropTypeDefaultDescription
variant
defaultsecondaryoutlineghostdestructivelink
—The visual style.
size
xssmdefaultlgicon-xsicon-smiconicon-lg
—The dimensions.
classNamestring—Additional classes merged with cn().

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

  • 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.