Button
Actions people press. The standard set, plus buttons that confirm on hold, report their own result, or reveal their label. Three show a download as it runs, and one splits like liquid into the actions it holds.
Standard
Primary, secondary and tertiary actions with press feedback and a loading state that keeps its width.
Installation
$npx shadcn@latest add @stillui/buttonOr copy the source into your project. It needs the shadcn color tokens and the cn helper.
"use client";
// stillui.dev/components/button
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
import { forwardRef, type ComponentProps, type ReactNode } from "react";
import { cn } from "@/lib/utils";
// Press feedback lands inside ~100ms and settles without a visible wobble.
const PRESS = { type: "spring", stiffness: 700, damping: 40, mass: 0.6 } as const;
const SWAP = { duration: 0.16, ease: [0.16, 1, 0.3, 1] } as const;
// One primary action per view; secondary is quieter; tertiary reads like a link.
const variants = {
primary: "bg-primary text-primary-foreground shadow-raised hover:bg-primary/90",
secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/70",
tertiary: "bg-transparent text-muted-foreground hover:text-foreground hover:bg-secondary/60",
destructive: "bg-destructive text-white shadow-raised hover:bg-destructive/90",
} as const;
// Padding grows faster than the font so a large button feels larger, not zoomed.
const sizes = {
sm: "h-8 gap-1.5 px-3 text-[13px]",
md: "h-10 gap-2 px-4 text-sm",
lg: "h-12 gap-2.5 px-6 text-[15px]",
} as const;
type ButtonProps = Omit<ComponentProps<typeof motion.button>, "children"> & {
variant?: keyof typeof variants;
size?: keyof typeof sizes;
/** Keeps the button's width while showing a spinner in place of the label. */
loading?: boolean;
children?: ReactNode;
};
export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
{ variant = "primary", size = "md", loading = false, disabled, className, children, ...props },
ref,
) {
const reduce = useReducedMotion();
const inactive = disabled || loading;
return (
<motion.button
ref={ref}
disabled={inactive}
aria-busy={loading || undefined}
whileTap={inactive || reduce ? undefined : { scale: 0.97 }}
transition={PRESS}
className={cn(
"relative inline-flex shrink-0 select-none items-center justify-center rounded-md font-medium",
"transition-[background-color,color,opacity] duration-150 ease-out",
"disabled:pointer-events-none disabled:opacity-50 aria-busy:opacity-100",
"[&_svg]:size-4 [&_svg]:shrink-0",
variants[variant],
sizes[size],
className,
)}
{...props}
>
{/* The label stays in the layout so the width never jumps. */}
<motion.span
className="inline-flex items-center gap-[inherit]"
animate={{ opacity: loading ? 0 : 1, filter: loading && !reduce ? "blur(2px)" : "blur(0px)" }}
transition={SWAP}
>
{children}
</motion.span>
<AnimatePresence initial={false}>
{loading ? (
<motion.span
key="spinner"
className="absolute inset-0 grid place-items-center"
initial={{ opacity: 0, scale: reduce ? 1 : 0.8 }}
animate={{ opacity: 1, scale: 1 }}
exit={{ opacity: 0, scale: reduce ? 1 : 0.8 }}
transition={SWAP}
>
<Spinner />
<span className="sr-only">Loading</span>
</motion.span>
) : null}
</AnimatePresence>
</motion.button>
);
});
function Spinner() {
return (
<svg viewBox="0 0 16 16" fill="none" className="animate-spin motion-reduce:animate-none" aria-hidden>
<circle cx="8" cy="8" r="6.25" stroke="currentColor" strokeOpacity="0.25" strokeWidth="1.5" />
<path d="M14.25 8A6.25 6.25 0 0 0 8 1.75" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
</svg>
);
}States
- Idle
- Variant sets its place in the action hierarchy: one primary per view.
- Hover
- Background shifts one step. No movement.
- Pressed
- Scales to 97% on a stiff spring, felt within about 100ms.
- Focus
- Visible outline from the ring token, keyboard only.
- Loading
- Label blurs out in place, spinner fades in, width stays fixed. Announced as busy.
- Disabled
- Half opacity, no press response.
Notes
Destructive is for confirmation steps. On the page that starts a destructive flow, use secondary or tertiary.
Sizes change padding more than font size, so a large button feels larger rather than zoomed.
Hold to confirm
A destructive action that asks for a deliberate press-and-hold instead of a confirmation dialog.
Confirmed 0 times
Installation
$npx shadcn@latest add @stillui/button-holdOr copy the source into your project. It needs the shadcn color tokens and the cn helper.
"use client";
// stillui.dev/components/button#hold
import { animate, motion, useMotionValue, useTransform, type AnimationPlaybackControls } from "motion/react";
import { useId, useRef, useState, type KeyboardEvent, type ReactNode } from "react";
import { cn } from "@/lib/utils";
type ButtonHoldProps = {
children: ReactNode;
/** Runs once the button has been held for the full duration. */
onConfirm: () => void;
/** How long to hold, in milliseconds. */
duration?: number;
/** Shown briefly after confirming. */
doneLabel?: ReactNode;
className?: string;
};
/** A destructive action that needs a deliberate press-and-hold. Letting go early cancels it. */
export function ButtonHold({ children, onConfirm, duration = 1200, doneLabel = "Done", className }: ButtonHoldProps) {
const progress = useMotionValue(0);
const controls = useRef<AnimationPlaybackControls | null>(null);
const [done, setDone] = useState(false);
const hintId = useId();
// The filled layer is clipped from the right, so the label changes color exactly where the fill is.
const clipPath = useTransform(progress, (p) => `inset(0 ${100 - p * 100}% 0 0)`);
const start = () => {
if (done) return;
controls.current?.stop();
controls.current = animate(progress, 1, {
duration: (duration / 1000) * (1 - progress.get()),
ease: "linear",
onComplete: () => {
setDone(true);
onConfirm();
window.setTimeout(() => {
setDone(false);
animate(progress, 0, { duration: 0.3 });
}, 1400);
},
});
};
const cancel = () => {
if (done) return;
controls.current?.stop();
controls.current = animate(progress, 0, {
duration: 0.25,
ease: [0.16, 1, 0.3, 1],
});
};
const onKeyDown = (event: KeyboardEvent) => {
if ((event.key === " " || event.key === "Enter") && !event.repeat) {
event.preventDefault();
start();
}
};
const onKeyUp = (event: KeyboardEvent) => {
if (event.key === " " || event.key === "Enter") cancel();
};
const label = done ? doneLabel : children;
return (
<>
<button
type="button"
onPointerDown={start}
onPointerUp={cancel}
onPointerLeave={cancel}
onKeyDown={onKeyDown}
onKeyUp={onKeyUp}
onBlur={cancel}
onContextMenu={(event) => event.preventDefault()}
aria-describedby={hintId}
className={cn(
"relative inline-flex h-10 select-none items-center justify-center overflow-hidden rounded-md bg-secondary px-5 text-sm font-medium text-destructive [-webkit-touch-callout:none]",
className,
)}
>
<span className="inline-flex items-center gap-2">{label}</span>
<motion.span aria-hidden className="absolute inset-0 flex items-center justify-center gap-2 bg-destructive text-white" style={{ clipPath }}>
{label}
</motion.span>
<span role="status" className="sr-only">
{done ? doneLabel : ""}
</span>
</button>
<span id={hintId} hidden>
Press and hold to confirm
</span>
</>
);
}States
- Idle
- A quiet button with the label in the destructive color.
- Holding
- Red fills from the left at a steady pace; the label turns white exactly where the fill has reached.
- Let go early
- The fill drains back quickly and nothing happens.
- Confirmed
- Runs onConfirm and shows the done label for a moment, then resets.
- Keyboard
- Hold Space or Enter. Moving focus away cancels.
- Screen readers
- Described as “Press and hold to confirm” through aria-describedby, and the result is announced.
Notes
Use it for actions that are hard to undo. For everyday actions, a normal button with an undo toast is kinder.
The fill keeps moving with reduced motion turned on, because it is the only sign of progress.
Stateful
Follows its own request: idle, loading, then success or error. The button reshapes around each label.
Installation
$npx shadcn@latest add @stillui/button-statefulOr copy the source into your project. It needs the shadcn color tokens and the cn helper.
"use client";
// stillui.dev/components/button#stateful
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
import { useState, type ReactNode } from "react";
import { cn } from "@/lib/utils";
const SPRING = { type: "spring", stiffness: 420, damping: 34 } as const;
const RESET_AFTER = 1800;
type Phase = "idle" | "loading" | "success" | "error";
type ButtonStatefulProps = {
/** Return a promise; the button follows it to success or error. */
onClick: () => Promise<unknown>;
labels: Partial<Record<Phase, ReactNode>> & { idle: ReactNode };
className?: string;
};
/** A button that shows its own result. The width reshapes around each label. */
export function ButtonStateful({ onClick, labels, className }: ButtonStatefulProps) {
const reduce = useReducedMotion();
const [phase, setPhase] = useState<Phase>("idle");
const transition = reduce ? { duration: 0 } : SPRING;
const run = async () => {
if (phase !== "idle") return;
setPhase("loading");
let next: Phase = "success";
try {
await onClick();
} catch {
next = "error";
}
setPhase(next);
window.setTimeout(() => setPhase("idle"), RESET_AFTER);
};
const label = labels[phase] ?? labels.idle;
return (
<motion.button
layout={!reduce}
type="button"
onClick={run}
aria-busy={phase === "loading" || undefined}
transition={transition}
style={{ borderRadius: 8 }}
className={cn(
"inline-flex h-10 items-center justify-center overflow-hidden px-4 text-sm font-medium shadow-raised transition-[color,background-color,box-shadow,scale] active:scale-[0.97] duration-200",
phase === "error" ? "bg-destructive text-white" : phase === "success" ? "bg-success text-white" : "bg-primary text-primary-foreground",
className,
)}
>
<AnimatePresence mode="popLayout" initial={false}>
<motion.span
key={phase}
layout="position"
className="inline-flex items-center gap-2 whitespace-nowrap"
initial={{ opacity: 0, y: reduce ? 0 : 10, filter: reduce ? "none" : "blur(2px)" }}
animate={{ opacity: 1, y: 0, filter: "blur(0px)" }}
exit={{ opacity: 0, y: reduce ? 0 : -10, filter: reduce ? "none" : "blur(2px)" }}
transition={transition}
>
<PhaseIcon phase={phase} />
{label}
</motion.span>
</AnimatePresence>
<span role="status" className="sr-only">
{phase === "idle" ? "" : label}
</span>
</motion.button>
);
}
function PhaseIcon({ phase }: { phase: Phase }) {
if (phase === "idle") return null;
if (phase === "loading") {
return (
<svg viewBox="0 0 16 16" fill="none" className="size-4 animate-spin motion-reduce:animate-none" aria-hidden>
<circle cx="8" cy="8" r="6.25" stroke="currentColor" strokeOpacity="0.3" strokeWidth="1.5" />
<path d="M14.25 8A6.25 6.25 0 0 0 8 1.75" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
</svg>
);
}
return (
<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round" className="size-4" aria-hidden>
{phase === "success" ? (
<motion.path d="M3.5 8.5l3 3 6-7" initial={{ pathLength: 0 }} animate={{ pathLength: 1 }} transition={{ duration: 0.3, delay: 0.1 }} />
) : (
<path d="M8 4.5v4m0 3v.01" />
)}
</svg>
);
}States
- Idle
- A normal primary button.
- Loading
- A spinner and a present-tense label. Further clicks are ignored.
- Success
- Turns green with a check that draws itself.
- Error
- Turns red with a short reason, so people know it didn’t work.
- Reset
- Returns to idle after 1.8 seconds.
- Screen readers
- Each new label is announced through a live region.
Notes
Pass a function that returns a promise. A thrown error or rejection shows the error label.
Expand
A round icon button that reveals its label when you hover or focus it, so toolbars stay compact without guessing.
Installation
$npx shadcn@latest add @stillui/button-expandOr copy the source into your project. It needs the shadcn color tokens and the cn helper.
"use client";
// stillui.dev/components/button#expand
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
import { useState, type ComponentProps, type ReactNode } from "react";
import { cn } from "@/lib/utils";
const SPRING = { type: "spring", stiffness: 500, damping: 38 } as const;
type ButtonExpandProps = Omit<ComponentProps<"button">, "children"> & {
icon: ReactNode;
/** Always used as the accessible name; shown beside the icon on hover and focus. */
label: string;
};
/** An icon button that reveals its label when you reach for it. */
export function ButtonExpand({ icon, label, className, ...props }: ButtonExpandProps) {
const reduce = useReducedMotion();
const [open, setOpen] = useState(false);
const transition = reduce ? { duration: 0 } : SPRING;
return (
<button
type="button"
aria-label={label}
onPointerEnter={() => setOpen(true)}
onPointerLeave={() => setOpen(false)}
onFocus={() => setOpen(true)}
onBlur={() => setOpen(false)}
className={cn(
"inline-flex h-10 items-center rounded-full bg-card px-[11px] text-sm font-medium text-foreground shadow-raised transition-[color,background-color,box-shadow,scale] active:scale-[0.96] hover:bg-secondary [&_svg]:size-[18px] [&_svg]:shrink-0",
className,
)}
{...props}
>
{icon}
<AnimatePresence initial={false}>
{open ? (
<motion.span
aria-hidden
className="overflow-hidden whitespace-nowrap"
initial={{ width: 0, opacity: 0 }}
animate={{ width: "auto", opacity: 1 }}
exit={{ width: 0, opacity: 0 }}
transition={transition}
>
<span className="block pl-2 pr-1">{label}</span>
</motion.span>
) : null}
</AnimatePresence>
</button>
);
}States
- Resting
- Just the icon in a round, raised button.
- Reaching
- On hover or keyboard focus the label slides out and the button widens on a spring.
- Leaving
- The label tucks back in when the pointer or focus moves on.
- Screen readers
- The label is always the accessible name, even while hidden.
- Reduced motion
- The label appears and disappears without sliding.
Notes
Touch screens have no hover, so pick icons people recognise without the label.
Download
Fills with light as the download runs, and buds off a cancel button that rejoins the pill when it’s done.
Installation
$npx shadcn@latest add @stillui-pro/button-downloadA paid component. The command needs the token from your account in STILLUI_TOKEN; your account page shows the one-time setup.
This is a paid component. Its source and install come with access.
States
- Idle
- A light pill with a download arrow.
- Downloading
- The label grows to “Downloading”, a cancel button pulls away like a drop of liquid, and a soft glow fills from the left with progress.
- Done
- The arrow draws into a check, then the button settles back to idle.
- Cancelled
- The cancel button melts back in and focus returns to the main button.
- Failed
- Goes back to idle and announces the failure to screen readers.
- Reduced motion
- No blur, slide or liquid join. Labels and the cancel button fade.
Notes
Pass a function that receives onProgress and an AbortSignal. Call onProgress with values from 0 to 1, and stop work when the signal aborts.
The colors are the --download and --download-glow variables. Set them through className to recolor the button.
Progress
A download button whose outline draws itself as the download runs, closing into a full ring when it’s done.
Installation
$npx shadcn@latest add @stillui-pro/button-progressA paid component. The command needs the token from your account in STILLUI_TOKEN; your account page shows the one-time setup.
This is a paid component. Its source and install come with access.
States
- Idle
- A plain button with a faint outline.
- Downloading
- A line traces the outline clockwise from the top centre, with the percentage beside the label.
- Done
- The line meets itself, the arrow draws into a check, then the button settles back to idle.
- Width
- Sized to its longest label, so it never changes width between states.
- Failed
- Goes back to idle and announces the failure to screen readers.
- Reduced motion
- The line jumps to each new value instead of easing.
Notes
Pass a function that receives onProgress and an AbortSignal. Call onProgress with values from 0 to 1.
Icon
An icon-only download button. The arrow and tray pull apart into a spinner, which turns into a check when it’s done.
Installation
$npx shadcn@latest add @stillui/button-download-iconOr copy the source into your project. It needs the shadcn color tokens and the cn helper.
"use client";
// stillui.dev/components/button#icon
import { motion, useAnimate, useReducedMotion } from "motion/react";
import { useEffect, useRef, useState } from "react";
import { cn } from "@/lib/utils";
const DONE_FOR = 1600;
const EASE = [0.16, 1, 0.3, 1] as const;
type Phase = "idle" | "loading" | "done";
type ButtonDownloadIconProps = {
/** Start the download. The icon spins until the promise settles. */
onDownload: () => Promise<unknown>;
/** The accessible name. */
label?: string;
className?: string;
};
/** An icon-only download button. The arrow and tray pull apart into a spinner, which then becomes a check. */
export function ButtonDownloadIcon({
onDownload,
label = "Download",
className,
}: ButtonDownloadIconProps) {
const reduce = !!useReducedMotion();
const [phase, setPhase] = useState<Phase>("idle");
const [scope, animate] = useAnimate<HTMLButtonElement>();
const [status, setStatus] = useState("");
const alive = useRef(true);
useEffect(() => {
alive.current = true;
return () => {
alive.current = false;
};
}, []);
const start = async () => {
if (phase !== "idle") return;
setPhase("loading");
setStatus("Downloading");
try {
await onDownload();
if (!alive.current) return;
setPhase("done");
setStatus("Downloaded");
window.setTimeout(() => alive.current && setPhase("idle"), DONE_FOR);
} catch {
if (!alive.current) return;
setPhase("idle");
// A small shake, so people notice it didn’t work.
if (!reduce)
animate(scope.current, { x: [0, -4, 4, -3, 2, 0] }, { duration: 0.4 });
setStatus("Download failed");
}
};
const idle = phase === "idle";
const t = (duration: number, delay = 0) =>
reduce ? { duration: 0 } : { duration, delay, ease: EASE };
return (
<button
ref={scope}
type="button"
aria-label={label}
aria-busy={phase === "loading" || undefined}
aria-disabled={!idle || undefined}
onClick={start}
className={cn(
"relative grid size-11 shrink-0 place-items-center rounded-[14px] bg-card text-foreground shadow-raised outline-none transition-[scale,background-color] duration-150 hover:bg-secondary focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background active:scale-95 aria-disabled:hover:bg-card aria-disabled:active:scale-100",
className,
)}
>
<svg
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
strokeWidth="2"
strokeLinecap="round"
strokeLinejoin="round"
className="size-6"
aria-hidden
>
{/* The arrow shrinks up into a dot, where the spinner starts. */}
<motion.g
style={{ originX: 0.5, originY: 0 }}
initial={false}
animate={
idle
? { scale: 1, y: 0, opacity: 1 }
: { scale: 0, y: -1, opacity: 0 }
}
transition={idle ? t(0.45, 0.1) : t(0.3)}
>
<path d="M12 4v10" />
<path d="M7.5 9.5L12 14l4.5-4.5" />
</motion.g>
{/* The tray in two halves, each pulling back to its outer end. */}
{["M5 15v3a1 1 0 0 0 1 1h6", "M19 15v3a1 1 0 0 1-1 1h-6"].map((d) => (
<motion.path
key={d}
d={d}
initial={false}
animate={{ pathLength: idle ? 1 : 0, opacity: idle ? 1 : 0 }}
transition={{
pathLength: idle ? t(0.45, 0.15) : t(0.3),
opacity: {
duration: reduce ? 0 : idle ? 0 : 0.1,
delay: idle ? 0.15 : 0.25,
},
}}
/>
))}
{/* The spinner: an arc that grows from the dot and travels round. */}
<motion.g
style={{ originX: 0.5, originY: 0.5 }}
animate={
phase === "loading" && !reduce ? { rotate: 360 } : { rotate: 0 }
}
transition={
phase === "loading" && !reduce
? { duration: 0.9, ease: "linear", repeat: Infinity }
: { duration: 0 }
}
>
<motion.circle
cx="12"
cy="12"
r="8"
transform="rotate(-90 12 12)"
initial={false}
animate={
phase === "loading"
? {
pathLength: reduce ? 0.3 : [0.02, 0.4, 0.2, 0.4],
opacity: 1,
}
: { pathLength: 0.02, opacity: 0 }
}
transition={
phase === "loading"
? {
pathLength: reduce
? { duration: 0 }
: {
duration: 1.6,
delay: 0.2,
times: [0, 0.35, 0.7, 1],
repeat: Infinity,
repeatType: "mirror",
},
opacity: { duration: 0.1, delay: reduce ? 0 : 0.2 },
}
: { duration: reduce ? 0 : 0.15 }
}
/>
</motion.g>
{/* The check draws itself as the spinner lets go. */}
<motion.path
d="M6 12.5l4 4 8-9"
initial={false}
animate={
phase === "done"
? { pathLength: 1, opacity: 1 }
: { pathLength: 0, opacity: 0 }
}
transition={
phase === "done"
? {
pathLength: reduce
? { duration: 0 }
: {
type: "spring",
stiffness: 260,
damping: 20,
delay: 0.08,
},
opacity: { duration: 0.05 },
}
: { pathLength: t(0.25), opacity: t(0.2, 0.05) }
}
/>
</svg>
<span role="status" className="sr-only">
{status}
</span>
</button>
);
}States
- Idle
- A download arrow over a tray.
- Loading
- The tray pulls back to its ends and the arrow shrinks to a dot, which stretches into a spinning arc.
- Done
- The arc lets go and a check draws itself. After 1.6 seconds the arrow drops back in and the tray redraws.
- Failed
- A small shake, then back to idle. Screen readers hear that it failed.
- Screen readers
- The label names the button; each state is announced through a live region.
- Reduced motion
- The icons swap without drawing, and the spinner holds still.
Notes
Pass a function that returns a promise. The spinner runs until it settles. Give it a label that says what downloads.
Liquid
A round add button that splits like a drop of liquid into the actions it holds, and melts back together when closed.
Nothing here yet
Start your notebook with a photo or a written note.
Installation
$npx shadcn@latest add @stillui-pro/button-liquidA paid component. The command needs the token from your account in STILLUI_TOKEN; your account page shows the one-time setup.
This is a paid component. Its source and install come with access.
States
- Closed
- A single round button with a plus.
- Open
- The actions squeeze out to either side with a wobble and a few thrown drops. The plus turns into a smaller close button.
- Hover
- Each circle stretches toward the pointer, like liquid drawn to a finger. Mouse only.
- Choose
- Runs the action and melts back into one button, with focus returned to it.
- Keyboard
- Tab goes left action, button, right action. Escape closes.
- Reduced motion
- No liquid, wobble or drops. The actions appear in place.
Notes
Give it two or four actions; they split evenly to either side. More than four belong in a menu.
Every action needs a label. It becomes the button’s accessible name, since only the icon shows.
Uses the primary color, so it turns light in dark mode.