Documentation
Button
An animated button with variants, sizes, and support for leading and trailing icons.
Variants
Trailing icon
Leading icon
Sizes
Icon only
tsxapp/page.tsx
import { Button } from "@/components/ui/button";
export default function Example() {
return (
<div className="flex flex-wrap gap-4">
<Button>Continue</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="destructive">Destructive</Button>
</div>
);
}tsxcomponents/ui/button.tsx
"use client";
import React, { forwardRef } from "react";
import { motion, useReducedMotion, type HTMLMotionProps } from "motion/react";
import { cn } from "@/lib/utils";
import { SPRING_PRESS } from "@/lib/ease";
import { useHoverCapable } from "@/lib/hooks/use-hover-capable";
export type ButtonVariant =
| "default"
| "secondary"
| "outline"
| "ghost"
| "destructive";
export type ButtonSize = "sm" | "md" | "lg" | "icon";
export interface ButtonProps extends HTMLMotionProps<"button"> {
variant?: ButtonVariant;
size?: ButtonSize;
pressScale?: number;
className?: string;
children?: React.ReactNode;
}
export const buttonVariants = ({
variant = "default",
size = "md",
className,
}: {
variant?: ButtonVariant;
size?: ButtonSize;
className?: string;
} = {}) => {
const baseClasses =
"inline-flex items-center justify-center font-bold uppercase tracking-wider select-none whitespace-nowrap rounded-full transition-colors " +
"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background " +
"disabled:pointer-events-none disabled:opacity-50 " +
"[&_svg]:pointer-events-none [&_svg]:shrink-0 " +
"[&_svg]:rounded-full [&_svg]:transition-transform [&_svg]:duration-200 [&_svg]:ease-out hover:[&_svg]:scale-110 active:[&_svg]:scale-95";
const variantClasses: Record<ButtonVariant, string> = {
default:
"bg-primary text-primary-foreground hover:bg-primary/90 shadow-sm " +
"[&_svg]:bg-primary-foreground [&_svg]:text-primary",
secondary:
"bg-secondary text-secondary-foreground hover:bg-secondary/80 border border-border/40 " +
"[&_svg]:bg-card [&_svg]:text-foreground [&_svg]:border [&_svg]:border-border/30",
outline:
"border border-border bg-background text-foreground hover:bg-muted/60 hover:text-foreground " +
"[&_svg]:bg-muted [&_svg]:text-foreground",
ghost:
"text-muted-foreground hover:text-foreground hover:bg-muted/60 " +
"[&_svg]:bg-muted/70 [&_svg]:text-foreground",
destructive:
"bg-destructive text-destructive-foreground hover:bg-destructive/90 shadow-sm " +
"[&_svg]:bg-destructive-foreground [&_svg]:text-destructive",
};
const sizeClasses: Record<ButtonSize, string> = {
sm: "h-9 px-4 text-xs gap-2.5 [&_svg]:size-6 [&_svg]:p-1",
md: "h-11 px-5 text-xs sm:text-sm gap-3.5 [&_svg]:size-8 [&_svg]:p-1.5",
lg: "h-14 px-7 text-sm sm:text-base gap-4 [&_svg]:size-9 [&_svg]:p-2",
icon: "size-11 p-0 rounded-full [&_svg]:size-7 [&_svg]:p-1.5",
};
return cn(baseClasses, variantClasses[variant], sizeClasses[size], className);
};
export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
(
{
variant = "default",
size = "md",
pressScale = 0.96,
className,
children,
...props
},
ref,
) => {
const reduceMotion = useReducedMotion();
const canHover = useHoverCapable();
const childrenArray = React.Children.toArray(children);
const hasMultiple = childrenArray.length > 1;
const isFirstElement =
hasMultiple && React.isValidElement(childrenArray[0]);
const isLastElement =
hasMultiple &&
React.isValidElement(childrenArray[childrenArray.length - 1]);
const edgePadding =
size === "icon"
? "p-0"
: isFirstElement && !isLastElement
? size === "sm"
? "pl-1.5 pr-4"
: size === "lg"
? "pl-2 pr-7"
: "pl-1.5 pr-5"
: isLastElement && !isFirstElement
? size === "sm"
? "pl-4 pr-1.5"
: size === "lg"
? "pl-7 pr-2"
: "pl-5 pr-1.5"
: "";
return (
<motion.button
ref={ref}
type="button"
whileHover={reduceMotion || !canHover ? undefined : { scale: 1.03 }}
whileTap={reduceMotion ? undefined : { scale: pressScale }}
transition={SPRING_PRESS}
className={cn(
buttonVariants({ variant, size, className }),
edgePadding,
)}
{...props}
>
{children}
</motion.button>
);
},
);
Button.displayName = "Button";
export default Button;
Installation
Initialize your project once, then add Button. The CLI copies the source and installs its dependencies.
$bunx knot-ui init$bunx knot-ui add buttonUse a TypeScript project with Tailwind CSS v4 and an @/ alias pointing to your source folder. Need the theme tokens? Follow the project setup once.
1. Install dependencies
$bun add clsx tailwind-merge motion2. Add shared helpers
Copy these files into your source folder. Reuse them if they already exist.
tsxlib/utils.ts
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
tsxlib/ease.ts
export const EASE_OUT = [0.16, 1, 0.3, 1] as const;
export const EASE_IN_OUT = [0.77, 0, 0.175, 1] as const;
export const EASE_DRAWER = [0.32, 0.72, 0, 1] as const;
/** CSS string form of EASE_OUT for inline style transitions. */
export const EASE_OUT_CSS = "cubic-bezier(0.16, 1, 0.3, 1)";
/** Press feedback on buttons and other tappable surfaces. */
export const SPRING_PRESS = {
type: "spring",
stiffness: 500,
damping: 30,
mass: 0.6,
} as const;
/** Content swaps — label/icon slots trading places inside a control. */
export const SPRING_SWAP = {
type: "spring",
stiffness: 460,
damping: 30,
mass: 0.55,
} as const;
/** Overlay panel entrances — modals and sheets summoned by pointer. */
export const SPRING_PANEL = {
type: "spring",
stiffness: 420,
damping: 40,
mass: 0.5,
} as const;
/** Shared-layout glides — pills, indicators and panels morphing between positions. */
export const SPRING_LAYOUT = {
type: "spring",
stiffness: 360,
damping: 32,
mass: 0.6,
} as const;
/** Cursor-follow physics for decorative mouse tracking (magnetic, tilt, dock). */
export const SPRING_MOUSE = {
stiffness: 200,
damping: 15,
mass: 0.3,
} as const;
/** Dragged handles and fills (sliders) — critically damped `useSpring` config,
* so the value follows the pointer butterily and never rebounds off an end. */
export const SPRING_GLIDE = {
stiffness: 700,
damping: 50,
mass: 0.5,
} as const;
tsxlib/hooks/use-hover-capable.ts
"use client";
import { useEffect, useState } from "react";
/**
* Returns true only on devices that have a true hover (mouse / trackpad).
* Touch devices fire phantom `:hover` on tap that sticks until tap-elsewhere
* — gate hover-only effects (scale lifts, magnetic pulls) behind this.
*/
export function useHoverCapable() {
const [canHover, setCanHover] = useState(false);
useEffect(() => {
if (typeof window === "undefined" || !window.matchMedia) return;
const mq = window.matchMedia("(hover: hover) and (pointer: fine)");
const update = () => setCanHover(mq.matches);
update();
mq.addEventListener?.("change", update);
return () => mq.removeEventListener?.("change", update);
}, []);
return canHover;
}
3. Copy the component
tsxcomponents/ui/button.tsx
"use client";
import React, { forwardRef } from "react";
import { motion, useReducedMotion, type HTMLMotionProps } from "motion/react";
import { cn } from "@/lib/utils";
import { SPRING_PRESS } from "@/lib/ease";
import { useHoverCapable } from "@/lib/hooks/use-hover-capable";
export type ButtonVariant =
| "default"
| "secondary"
| "outline"
| "ghost"
| "destructive";
export type ButtonSize = "sm" | "md" | "lg" | "icon";
export interface ButtonProps extends HTMLMotionProps<"button"> {
variant?: ButtonVariant;
size?: ButtonSize;
pressScale?: number;
className?: string;
children?: React.ReactNode;
}
export const buttonVariants = ({
variant = "default",
size = "md",
className,
}: {
variant?: ButtonVariant;
size?: ButtonSize;
className?: string;
} = {}) => {
const baseClasses =
"inline-flex items-center justify-center font-bold uppercase tracking-wider select-none whitespace-nowrap rounded-full transition-colors " +
"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background " +
"disabled:pointer-events-none disabled:opacity-50 " +
"[&_svg]:pointer-events-none [&_svg]:shrink-0 " +
"[&_svg]:rounded-full [&_svg]:transition-transform [&_svg]:duration-200 [&_svg]:ease-out hover:[&_svg]:scale-110 active:[&_svg]:scale-95";
const variantClasses: Record<ButtonVariant, string> = {
default:
"bg-primary text-primary-foreground hover:bg-primary/90 shadow-sm " +
"[&_svg]:bg-primary-foreground [&_svg]:text-primary",
secondary:
"bg-secondary text-secondary-foreground hover:bg-secondary/80 border border-border/40 " +
"[&_svg]:bg-card [&_svg]:text-foreground [&_svg]:border [&_svg]:border-border/30",
outline:
"border border-border bg-background text-foreground hover:bg-muted/60 hover:text-foreground " +
"[&_svg]:bg-muted [&_svg]:text-foreground",
ghost:
"text-muted-foreground hover:text-foreground hover:bg-muted/60 " +
"[&_svg]:bg-muted/70 [&_svg]:text-foreground",
destructive:
"bg-destructive text-destructive-foreground hover:bg-destructive/90 shadow-sm " +
"[&_svg]:bg-destructive-foreground [&_svg]:text-destructive",
};
const sizeClasses: Record<ButtonSize, string> = {
sm: "h-9 px-4 text-xs gap-2.5 [&_svg]:size-6 [&_svg]:p-1",
md: "h-11 px-5 text-xs sm:text-sm gap-3.5 [&_svg]:size-8 [&_svg]:p-1.5",
lg: "h-14 px-7 text-sm sm:text-base gap-4 [&_svg]:size-9 [&_svg]:p-2",
icon: "size-11 p-0 rounded-full [&_svg]:size-7 [&_svg]:p-1.5",
};
return cn(baseClasses, variantClasses[variant], sizeClasses[size], className);
};
export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
(
{
variant = "default",
size = "md",
pressScale = 0.96,
className,
children,
...props
},
ref,
) => {
const reduceMotion = useReducedMotion();
const canHover = useHoverCapable();
const childrenArray = React.Children.toArray(children);
const hasMultiple = childrenArray.length > 1;
const isFirstElement =
hasMultiple && React.isValidElement(childrenArray[0]);
const isLastElement =
hasMultiple &&
React.isValidElement(childrenArray[childrenArray.length - 1]);
const edgePadding =
size === "icon"
? "p-0"
: isFirstElement && !isLastElement
? size === "sm"
? "pl-1.5 pr-4"
: size === "lg"
? "pl-2 pr-7"
: "pl-1.5 pr-5"
: isLastElement && !isFirstElement
? size === "sm"
? "pl-4 pr-1.5"
: size === "lg"
? "pl-7 pr-2"
: "pl-5 pr-1.5"
: "";
return (
<motion.button
ref={ref}
type="button"
whileHover={reduceMotion || !canHover ? undefined : { scale: 1.03 }}
whileTap={reduceMotion ? undefined : { scale: pressScale }}
transition={SPRING_PRESS}
className={cn(
buttonVariants({ variant, size, className }),
edgePadding,
)}
{...props}
>
{children}
</motion.button>
);
},
);
Button.displayName = "Button";
export default Button;
Usage
tsxapp/page.tsx
import { Button } from "@/components/ui/button";
export default function Example() {
return (
<div className="flex flex-wrap gap-4">
<Button>Continue</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="destructive">Destructive</Button>
</div>
);
}Props
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "default" | "secondary" | "outline" | "ghost" | "destructive" | "default" | The visual style of the button. |
| size | "sm" | "md" | "lg" | "icon" | "md" | The dimensions and spacing of the button. |
| pressScale | number | 0.96 | The scale while pressing. Reduced motion disables this animation. |
| className | string | — | Additional Tailwind classes. |
| children | ReactNode | — | The button label and optional icons. |
Standard button attributes and Motion button properties are supported. Give icon-only buttons an accessible label.