Onboarding Checklist
Getting-started card with a progress ring and bar and steps that expand to a description and an async CTA; finishing a step pops its check, strikes its title and opens the next unfinished step, and at 100% the list gives way to a confetti celebration, with a dismiss that animates the card away.
Preview
Install
Add it with the shadcn CLI, or copy the source manually.
shadcn init? You are set. Theme setupInstall dependencies
npm i clsx lucide-react motion tailwind-mergeAdd util files
// Shared motion tokens. Easing curves mirror the CSS custom properties in
// globals.css; springs are the canonical physics used across components.
// Strong custom variants — defaults like `ease-in`/`ease-out` feel weak.
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;
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs))
}
"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;
}
// Shared touch primitives. iOS and iPadOS run their own gestures on top of the
// page — the long-press selection callout and the selection it drags in with
// it — and they win: once the platform claims a touch it cancels ours
// mid-gesture, so a press-and-hold or a drag simply dies. Surfaces that own
// their gesture have to opt out.
//
// What the two classes below cover, precisely:
// - `-webkit-touch-callout: none` stops iOS's long-press callout. WebKit-only:
// it is not a property other engines have, so it is inert everywhere else.
// - `user-select: none` stops the long-press selection on every engine,
// Android included, and stops a drag from painting a selection under the
// cursor. It is inherited, so it reaches every descendant — which is why the
// two classes differ only in whether they apply it unconditionally.
// What neither covers:
// - Chrome for Android's long-press menu on a link or an image. No CSS
// suppresses it; a gesture surface that wraps one needs its own
// `onContextMenu` with `preventDefault()`.
// - The native drag of an `<img>` or `<a>` descendant. `-webkit-user-drag` is
// not inherited and plain divs and buttons are not drag sources, so setting
// it on the surface does nothing — the child itself needs `draggable={false}`.
/**
* Classes for a surface that *is* the control: a thumb, a drum, a stage, a
* handle, a hold button. Selection is suppressed on every input, because a
* drag that highlights the control's own label is wrong on a mouse too.
* Compose with `touch-none` when the surface also owns the scroll axis — leave
* it off when the page must still scroll from there.
*/
export const TOUCH_GESTURE_CLASS = "select-none [-webkit-touch-callout:none]";
/**
* The same opt-out for a gesture surface that wraps content the consumer owns:
* a scroller, a context-menu trigger, a sheet header, a list row. Selection is
* suppressed only where the platform runs its own press gestures — a coarse
* pointer — so a mouse user can still select and copy that content. If the
* gesture itself would paint a selection under the cursor, add `select-none`
* for the duration of the gesture rather than reaching for
* `TOUCH_GESTURE_CLASS`.
*
* `pointer: coarse` describes the *primary* pointer and nothing else, so a
* hybrid machine reads it wrong in both directions: a tablet with a mouse
* plugged in keeps touch as primary and loses mouse selection, and a laptop
* with a touchscreen keeps the mouse as primary and leaves selection live
* under a finger. No media query can answer per interaction — the query is
* about the device, and the question is about the gesture in progress. The
* default stays here because it is right on the machines that are one thing or
* the other, and losing a selection is a nuisance; where the miss costs a
* *gesture* instead, the surface pairs it with `holdSelection` on the press.
*/
export const TOUCH_GESTURE_CONTENT_CLASS =
"[-webkit-touch-callout:none] pointer-coarse:select-none";
/**
* Grow a small control's *hit area* to at least 44×44px (WCAG 2.5.5, Apple
* HIG) on a coarse pointer, without changing what it looks like or the space
* it takes in layout. An invisible `::after` box, centered on the control and
* `max(100%, 2.75rem)` on each axis, catches the taps: a 32px icon button
* reaches 6px past each edge, a wide 40px button only grows vertically, and a
* control already 44px or larger is left as it is. Hit-testing a pseudo
* element lands on its owner, so handlers, focus and `:active` all behave.
*
* Mouse and trackpad rendering is untouched — nothing here applies outside
* `pointer: coarse`. Requirements on the element it goes on:
* - It must be the containing block: add `relative` (and keep it mergeable, so
* a consumer's `absolute` still wins through `cn`).
* - It must not clip itself (`overflow-hidden`), or the overhang is clipped
* away along with its hit area.
* - It must render children: `<input>` and other void elements have no
* `::after`. Put it on the wrapper or label instead.
* - It must not already use `::after` for something visible.
*
* Centered 44px means two 32px buttons with a 4px gap overlap by 8px; the
* later one wins that strip, which still ends well short of the earlier
* button's visual center. Below a ~32px pitch the later neighbour starts
* eating into that center — use `TOUCH_TARGET_Y_CLASS` for such dense rows.
*
* The overhang is real geometry: inside a scroll container it counts as
* scrollable overflow, so a control flush against a scroller's edge can add a
* few pixels of scroll on touch screens. Give such a scroller a little padding
* on that side.
*/
export const TOUCH_TARGET_CLASS =
"pointer-coarse:after:absolute pointer-coarse:after:top-1/2 pointer-coarse:after:left-1/2 pointer-coarse:after:size-[max(100%,2.75rem)] pointer-coarse:after:-translate-x-1/2 pointer-coarse:after:-translate-y-1/2 pointer-coarse:after:content-['']";
/**
* `TOUCH_TARGET_CLASS` on the vertical axis only, for controls packed tighter
* than ~32px apart in a row (pagination dots, dense swatches), where growing
* sideways would hand most of each control to its neighbour. Same rules.
*/
export const TOUCH_TARGET_Y_CLASS =
"pointer-coarse:after:absolute pointer-coarse:after:inset-x-0 pointer-coarse:after:top-1/2 pointer-coarse:after:h-[max(100%,2.75rem)] pointer-coarse:after:-translate-y-1/2 pointer-coarse:after:content-['']";
/**
* Suppress selection on `element` for as long as a gesture is running on it,
* whatever the primary pointer of the machine happens to be. Returns the
* release. Inline, so it wins over the class above and is gone again the
* moment the gesture ends.
*
* For the press gestures a native selection would otherwise steal — a
* long-press that opens a menu. Elsewhere prefer the classes: a surface that
* takes selection away for the whole session is a surface whose text nobody
* can copy.
*/
export function holdSelection(element: HTMLElement) {
element.style.setProperty("user-select", "none");
element.style.setProperty("-webkit-user-select", "none");
return () => {
element.style.removeProperty("user-select");
element.style.removeProperty("-webkit-user-select");
};
}
/**
* Pointer capture, best effort. WebKit throws `NotFoundError` when the pointer
* is already gone by the time the handler runs — routine on iOS, where the
* system can claim the touch first — and an uncaught throw takes the rest of
* the handler, the gesture included, down with it. Touch pointers carry
* implicit capture anyway, so losing it is never fatal.
*/
export function capturePointer(element: Element, pointerId: number) {
try {
element.setPointerCapture(pointerId);
} catch {
// Pointer is no longer active — implicit capture still applies on touch.
}
}
/** Release a capture taken with `capturePointer`, ignoring a stale pointer. */
export function releasePointer(element: Element, pointerId: number) {
try {
if (element.hasPointerCapture(pointerId)) {
element.releasePointerCapture(pointerId);
}
} catch {
// Capture was already dropped by the browser.
}
}
/**
* Whether this event came from a pointer that is *hovering*: not a touch, and
* not currently pressed. Which input the user is holding right now is not
* something a device capability can answer — a touchscreen laptop hovers and
* taps, and iPadOS reports a fine hovering pointer for a finger — so both
* paths stay live and each handler branches on the event it was given.
*
* A pen resting on the glass is making contact, not hovering: `buttons` is the
* tell, and it sends a pen tap down the same route a finger takes.
*
* This answers what an *enter* asks. A leave is the other half of a pair and
* has to be read against the enter that started it — `useHoverGesture` in
* `lib/hooks/use-hover-gesture` does that, and hover surfaces should use it
* rather than asking this question twice.
*/
export const isHoveringPointer = (event: {
pointerType: string;
buttons: number;
}) => event.pointerType !== "touch" && event.buttons === 0;
Copy the source code
"use client";
// karaui.kamisama-v0.my.id/components/blocks/onboarding-checklist
import { ChevronDown, PartyPopper, X } from "lucide-react";
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
import { type ReactNode, useEffect, useRef, useState } from "react";
import { Button, StatefulButton } from "@/components/motion/button";
import {
Collapsible,
CollapsibleContent,
CollapsibleTrigger,
} from "@/components/motion/collapsible";
import { Progress, ProgressCircle } from "@/components/motion/progress";
import { EASE_OUT, SPRING_SWAP } from "@/lib/ease";
import { cn } from "@/lib/utils";
export type OnboardingStep = {
id: string;
title: string;
description?: ReactNode;
/** CTA label inside the expanded step. Default "Mark as done". */
actionLabel?: string;
/** Runs when the CTA is pressed; the step completes once it resolves. */
onAction?: () => void | Promise<void>;
};
export interface OnboardingChecklistProps {
steps: OnboardingStep[];
/** Controlled completed step ids. */
completed?: string[];
defaultCompleted?: string[];
onCompletedChange?: (completed: string[]) => void;
/** Controlled visibility. Dismissing sets it to false. */
open?: boolean;
defaultOpen?: boolean;
onOpenChange?: (open: boolean) => void;
dismissible?: boolean;
title?: ReactNode;
description?: ReactNode;
celebrationTitle?: ReactNode;
celebrationDescription?: ReactNode;
className?: string;
}
const NEXT_OPEN_DELAY_MS = 420;
const CONFETTI_COLORS = ["bg-chart-1", "bg-chart-2", "bg-chart-3", "bg-chart-4", "bg-chart-5"];
// Deterministic burst: evenly spaced angles, alternating distances.
const CONFETTI = Array.from({ length: 16 }, (_, i) => {
const angle = (i / 16) * Math.PI * 2;
const distance = i % 2 === 0 ? 74 : 54;
return {
id: i,
x: Math.round(Math.cos(angle) * distance),
y: Math.round(Math.sin(angle) * distance),
color: CONFETTI_COLORS[i % CONFETTI_COLORS.length],
round: i % 3 === 0,
};
});
function CheckMark({ done }: { done: boolean }) {
const reduce = useReducedMotion();
return (
<span className="relative grid size-5 shrink-0 place-items-center">
<span
className={cn(
"absolute inset-0 rounded-full border-2 transition-colors duration-200",
done ? "border-primary" : "border-border-strong",
)}
/>
<motion.span
initial={false}
animate={{ scale: done ? 1 : reduce ? 1 : 0.3, opacity: done ? 1 : 0 }}
transition={reduce ? { duration: 0.15 } : SPRING_SWAP}
className="absolute inset-0 rounded-full bg-primary"
/>
<svg viewBox="0 0 20 20" className="relative size-3.5 text-primary-foreground" fill="none" aria-hidden="true">
<motion.path
d="M5 10.5l3.2 3.2L15 7"
stroke="currentColor"
strokeWidth={2.4}
strokeLinecap="round"
strokeLinejoin="round"
initial={false}
animate={{ pathLength: done ? 1 : 0, opacity: done ? 1 : 0 }}
transition={{ duration: reduce ? 0 : 0.28, delay: done && !reduce ? 0.08 : 0, ease: EASE_OUT }}
/>
</svg>
</span>
);
}
/**
* Getting-started card: a progress ring and bar, steps that expand (via
* `Collapsible`) to show a description and CTA, a completed step pops its
* check, strikes its title and auto-opens the next open step, an optional
* dismiss, and a confetti celebration state once everything is done.
*/
export function OnboardingChecklist({
steps,
completed: completedProp,
defaultCompleted = [],
onCompletedChange,
open: openProp,
defaultOpen = true,
onOpenChange,
dismissible = true,
title = "Get started",
description = "A few steps to set up your workspace.",
celebrationTitle = "You're all set!",
celebrationDescription = "Your workspace is ready. Time to build something.",
className,
}: OnboardingChecklistProps) {
const reduce = useReducedMotion();
const [internalCompleted, setInternalCompleted] = useState(defaultCompleted);
const completed = completedProp ?? internalCompleted;
const [internalOpen, setInternalOpen] = useState(defaultOpen);
const visible = openProp ?? internalOpen;
const [expanded, setExpanded] = useState<string | null>(
() => steps.find((s) => !defaultCompleted.includes(s.id))?.id ?? null,
);
const [pending, setPending] = useState<string | null>(null);
const timer = useRef<number | undefined>(undefined);
useEffect(() => () => window.clearTimeout(timer.current), []);
const doneCount = steps.filter((s) => completed.includes(s.id)).length;
const allDone = steps.length > 0 && doneCount === steps.length;
const percent = steps.length ? Math.round((doneCount / steps.length) * 100) : 0;
const commit = (next: string[]) => {
if (completedProp === undefined) setInternalCompleted(next);
onCompletedChange?.(next);
};
const setDone = (id: string, done: boolean) => {
const next = done
? [...completed.filter((c) => c !== id), id]
: completed.filter((c) => c !== id);
commit(next);
if (!done) return;
window.clearTimeout(timer.current);
// Let the check land before the next step unfolds.
timer.current = window.setTimeout(() => {
const index = steps.findIndex((s) => s.id === id);
const following = [...steps.slice(index + 1), ...steps.slice(0, index)].find(
(s) => !next.includes(s.id),
);
setExpanded(following?.id ?? null);
}, NEXT_OPEN_DELAY_MS);
};
const runAction = async (step: OnboardingStep) => {
setPending(step.id);
try {
await step.onAction?.();
setDone(step.id, true);
} finally {
setPending(null);
}
};
const dismiss = () => {
if (openProp === undefined) setInternalOpen(false);
onOpenChange?.(false);
};
return (
<AnimatePresence initial={false}>
{visible ? (
<motion.section
key="checklist"
aria-label="Onboarding checklist"
initial={reduce ? { opacity: 0 } : { opacity: 0, y: 12, scale: 0.98 }}
animate={{ opacity: 1, y: 0, scale: 1 }}
exit={
reduce
? { opacity: 0 }
: { opacity: 0, y: 8, scale: 0.96, transition: { duration: 0.18, ease: EASE_OUT } }
}
transition={{ duration: 0.28, ease: EASE_OUT }}
className={cn(
"w-full max-w-md overflow-hidden rounded-3xl border border-border bg-card p-5",
className,
)}
>
<header className="flex items-start gap-3.5">
<ProgressCircle
value={percent}
size={44}
thickness={4}
aria-label="Onboarding progress"
className="shrink-0 text-[11px]"
/>
<div className="min-w-0 flex-1">
<h2 className="text-base font-semibold tracking-tight text-foreground">{title}</h2>
<p className="text-sm text-muted-foreground">
{allDone ? "Everything's done." : description}{" "}
<span className="tabular-nums">
{doneCount}/{steps.length}
</span>
</p>
</div>
{dismissible ? (
<button
type="button"
aria-label="Dismiss checklist"
onClick={dismiss}
className="grid size-8 shrink-0 place-items-center rounded-full text-muted-foreground outline-none transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
>
<X className="size-4" aria-hidden />
</button>
) : null}
</header>
<Progress
value={percent}
size="sm"
aria-label="Steps completed"
showValue={false}
className="mt-4"
trackClassName="bg-foreground/10"
/>
<AnimatePresence mode="wait" initial={false}>
{allDone ? (
<motion.div
key="celebrate"
role="status"
initial={reduce ? { opacity: 0 } : { opacity: 0, scale: 0.94 }}
animate={{ opacity: 1, scale: 1 }}
exit={{ opacity: 0, transition: { duration: 0.12 } }}
transition={{ duration: 0.3, ease: EASE_OUT }}
className="flex flex-col items-center gap-3 pt-8 pb-3 text-center"
>
<span className="relative grid size-16 place-items-center">
{reduce
? null
: CONFETTI.map((piece) => (
<motion.span
key={piece.id}
aria-hidden
initial={{ x: 0, y: 0, opacity: 1, scale: 0.6 }}
animate={{ x: piece.x, y: piece.y, opacity: 0, scale: 1 }}
transition={{ duration: 0.9, delay: 0.1, ease: EASE_OUT }}
className={cn(
"absolute top-1/2 left-1/2 -mt-1 -ml-1 size-2",
piece.round ? "rounded-full" : "rounded-xs",
piece.color,
)}
/>
))}
<motion.span
initial={reduce ? { opacity: 0 } : { opacity: 0, scale: 0.4, rotate: -20 }}
animate={{ opacity: 1, scale: 1, rotate: 0 }}
transition={reduce ? { duration: 0.2 } : SPRING_SWAP}
className="grid size-16 place-items-center rounded-full bg-muted text-foreground"
>
<PartyPopper className="size-7" aria-hidden />
</motion.span>
</span>
<div>
<p className="text-base font-semibold text-foreground">{celebrationTitle}</p>
<p className="text-sm text-muted-foreground">{celebrationDescription}</p>
</div>
<div className="flex gap-2">
<Button size="sm" variant="ghost" onClick={() => commit([])}>
Start over
</Button>
{dismissible ? (
<Button size="sm" onClick={dismiss}>
Dismiss
</Button>
) : null}
</div>
</motion.div>
) : (
<motion.ul
key="steps"
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0, transition: { duration: 0.12 } }}
className="mt-3 flex flex-col"
>
{steps.map((step) => {
const done = completed.includes(step.id);
const isOpen = expanded === step.id;
return (
<li key={step.id} className="border-b border-border last:border-b-0">
<Collapsible
open={isOpen}
onOpenChange={(next) => setExpanded(next ? step.id : null)}
>
<div className="flex items-center gap-3 py-2.5">
<button
type="button"
aria-pressed={done}
aria-label={`Mark "${step.title}" as ${done ? "not done" : "done"}`}
onClick={() => setDone(step.id, !done)}
className="rounded-full outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-card"
>
<CheckMark done={done} />
</button>
<CollapsibleTrigger className="group flex min-w-0 flex-1 items-center justify-between gap-2 rounded-lg text-left outline-none focus-visible:ring-2 focus-visible:ring-ring">
<span className="relative min-w-0 truncate">
<span
className={cn(
"text-sm font-medium transition-colors duration-200",
done ? "text-muted-foreground" : "text-foreground",
)}
>
{step.title}
</span>
{/* Strike line draws left→right on an HTML span. */}
<motion.span
aria-hidden
initial={false}
animate={{ scaleX: done ? 1 : 0 }}
transition={{ duration: reduce ? 0 : 0.3, ease: EASE_OUT }}
className="absolute top-1/2 left-0 h-px w-full origin-left bg-muted-foreground"
/>
</span>
<motion.span
aria-hidden
animate={{ rotate: isOpen ? 180 : 0 }}
transition={reduce ? { duration: 0 } : SPRING_SWAP}
className="shrink-0 text-muted-foreground"
>
<ChevronDown className="size-4" />
</motion.span>
</CollapsibleTrigger>
</div>
<CollapsibleContent innerClassName="pb-3 pl-8">
{step.description ? (
<p className="text-sm text-muted-foreground">{step.description}</p>
) : null}
{done ? (
<p className="mt-2 text-xs font-medium text-success">Completed</p>
) : (
<StatefulButton
size="sm"
className="mt-2.5"
state={pending === step.id ? "loading" : "idle"}
loadingText="Working"
onClick={() => void runAction(step)}
>
{step.actionLabel ?? "Mark as done"}
</StatefulButton>
)}
</CollapsibleContent>
</Collapsible>
</li>
);
})}
</motion.ul>
)}
</AnimatePresence>
</motion.section>
) : null}
</AnimatePresence>
);
}
export type {
ButtonLinkProps,
ButtonProps,
ButtonSize,
ButtonVariant,
} from "./base";
export { Button, ButtonLink } from "./base";
export type { MagneticButtonProps } from "./magnetic";
export { MagneticButton } from "./magnetic";
export type { ButtonState, StatefulButtonProps } from "./stateful";
export { StatefulButton } from "./stateful";
"use client";
import { motion, useReducedMotion, type Transition } from "motion/react";
import {
cloneElement,
createContext,
forwardRef,
isValidElement,
useCallback,
useContext,
useId,
useState,
type ButtonHTMLAttributes,
type HTMLAttributes,
type MouseEvent,
type ReactElement,
type ReactNode,
} from "react";
import { EASE_OUT } from "@/lib/ease";
import { cn } from "@/lib/utils";
// Collapsible is the unstyled disclosure primitive: one trigger, one panel.
// `Accordion` (accordion.tsx) is built from it; `BouncyAccordion` is the
// springy, single-open icon-row variant. Reach for this when a single region
// should show or hide in flow ("Show 3 more", an expandable activity row).
/** Entrance is a touch longer than the exit — exits should feel faster. */
const OPEN_TRANSITION: Transition = { duration: 0.28, ease: EASE_OUT };
const CLOSE_TRANSITION: Transition = { duration: 0.2, ease: EASE_OUT };
interface CollapsibleContextValue {
open: boolean;
setOpen: (open: boolean) => void;
disabled: boolean;
triggerId: string;
contentId: string;
}
const CollapsibleContext = createContext<CollapsibleContextValue | null>(null);
export function useCollapsible(component = "useCollapsible") {
const context = useContext(CollapsibleContext);
if (!context) {
throw new Error(`${component} must be used within <Collapsible>.`);
}
return context;
}
export interface CollapsibleProps
extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
/** Controlled open state. */
open?: boolean;
/** Initial open state when uncontrolled. */
defaultOpen?: boolean;
onOpenChange?: (open: boolean) => void;
disabled?: boolean;
/** Override the generated trigger id (the content is labelled by it). */
triggerId?: string;
/** Override the generated content id (the trigger controls it). */
contentId?: string;
children?: ReactNode;
}
export const Collapsible = forwardRef<HTMLDivElement, CollapsibleProps>(
function Collapsible(
{
open: openProp,
defaultOpen = false,
onOpenChange,
disabled = false,
triggerId: triggerIdProp,
contentId: contentIdProp,
className,
children,
...rest
},
ref,
) {
const [internal, setInternal] = useState(defaultOpen);
const controlled = openProp !== undefined;
const open = controlled ? openProp : internal;
const setOpen = useCallback(
(next: boolean) => {
if (!controlled) setInternal(next);
onOpenChange?.(next);
},
[controlled, onOpenChange],
);
const baseId = useId();
const triggerId = triggerIdProp ?? `${baseId}-trigger`;
const contentId = contentIdProp ?? `${baseId}-content`;
return (
<CollapsibleContext.Provider
value={{ open, setOpen, disabled, triggerId, contentId }}
>
<div
ref={ref}
data-state={open ? "open" : "closed"}
data-disabled={disabled ? "" : undefined}
className={cn(className)}
{...rest}
>
{children}
</div>
</CollapsibleContext.Provider>
);
},
);
type ClonableChild = ReactElement<{
onClick?: (event: MouseEvent<HTMLElement>) => void;
[key: string]: unknown;
}>;
export interface CollapsibleTriggerProps
extends ButtonHTMLAttributes<HTMLButtonElement> {
/** Merge trigger behaviour onto the single child element instead of rendering a `<button>`. */
asChild?: boolean;
}
/** Toggles the nearest `Collapsible`. Unstyled `<button>` by default. */
export const CollapsibleTrigger = forwardRef<
HTMLButtonElement,
CollapsibleTriggerProps
>(function CollapsibleTrigger(
{ asChild, children, onClick, className, disabled: disabledProp, ...rest },
ref,
) {
const context = useCollapsible("CollapsibleTrigger");
const disabled = context.disabled || Boolean(disabledProp);
const shared = {
id: context.triggerId,
"aria-expanded": context.open,
"aria-controls": context.contentId,
"data-state": context.open ? "open" : "closed",
"data-disabled": disabled ? "" : undefined,
};
if (asChild && isValidElement(children)) {
const child = children as ClonableChild;
return cloneElement(child, {
...shared,
onClick: (event: MouseEvent<HTMLElement>) => {
child.props.onClick?.(event);
if (!event.defaultPrevented && !disabled) context.setOpen(!context.open);
},
});
}
return (
<button
ref={ref}
type="button"
disabled={disabled}
className={cn(className)}
{...rest}
{...shared}
onClick={(event) => {
onClick?.(event);
if (!event.defaultPrevented) context.setOpen(!context.open);
}}
>
{children}
</button>
);
});
export interface CollapsibleContentProps extends HTMLAttributes<HTMLDivElement> {
/** Class for the inner wrapper that holds the children (padding goes here,
* never on the animated outer element, so the closed height is truly 0). */
innerClassName?: string;
/** Set to give the panel `role="region"` labelled by its trigger. */
region?: boolean;
children?: ReactNode;
}
/** The disclosed panel. Stays mounted (inert while closed) so `aria-controls` always resolves. */
export function CollapsibleContent({
className,
innerClassName,
region = false,
children,
style,
...rest
}: CollapsibleContentProps) {
const { open, triggerId, contentId } = useCollapsible("CollapsibleContent");
const reduce = useReducedMotion();
const fade = open ? OPEN_TRANSITION : CLOSE_TRANSITION;
return (
// Height is animated on purpose: disclosure is a layout job — the panel
// has to push the content below it down in flow, which transforms can't.
// Reduced motion snaps the height and keeps only the opacity fade.
<motion.div
{...(rest as Record<string, unknown>)}
id={contentId}
role={region ? "region" : undefined}
aria-labelledby={region ? triggerId : undefined}
data-state={open ? "open" : "closed"}
inert={!open}
initial={false}
animate={{ height: open ? "auto" : 0, opacity: open ? 1 : 0 }}
transition={
reduce ? { height: { duration: 0 }, opacity: { duration: 0.15 } } : fade
}
style={style}
className={cn("overflow-hidden", className)}
>
<div className={innerClassName}>{children}</div>
</motion.div>
);
}
"use client";
import {
motion,
useReducedMotion,
useSpring,
useTransform,
} from "motion/react";
import { type ReactNode, useEffect, useId, useRef } from "react";
import { NumberTicker } from "@/components/motion/number-ticker";
import { EASE_IN_OUT, EASE_OUT, SPRING_GLIDE } from "@/lib/ease";
import { cn } from "@/lib/utils";
export type ProgressSize = "sm" | "md" | "lg";
// Reduced motion: indeterminate states drop every transform and keep a calm
// opacity pulse (same rhythm as Loader's reduced variant).
const REDUCED_PULSE = {
animate: { opacity: [0.35, 0.85, 0.35] },
transition: { duration: 1.4, ease: EASE_IN_OUT, repeat: Infinity },
};
const clamp01 = (n: number) => (Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0);
/**
* A spring-smoothed 0..1 fraction. Uses SPRING_GLIDE (critically damped) so
* the fill never rebounds past the true value. Reduced motion jumps instead.
*/
function useFraction(fraction: number) {
const reduce = useReducedMotion();
const spring = useSpring(0, SPRING_GLIDE);
useEffect(() => {
if (reduce) spring.jump(fraction);
else spring.set(fraction);
}, [fraction, reduce, spring]);
return spring;
}
function defaultValueText(percent: number) {
return `${percent}%`;
}
interface ProgressCommonProps {
/** Current value. Omit (or pass `null`) together with `indeterminate`. */
value?: number | null;
/** Upper bound. Defaults to 100. */
max?: number;
/** Unknown-duration mode: a sliding segment (bar) or a spinning arc (circle). */
indeterminate?: boolean;
/** Visible label. When it is not a string, also pass `aria-label`. */
label?: ReactNode;
/** Show the rolling percentage. */
showValue?: boolean;
/** Screen-reader value text. Defaults to "42%". */
getValueText?: (percent: number, value: number, max: number) => string;
"aria-label"?: string;
className?: string;
}
function useProgressState(
value: number | null | undefined,
max: number,
indeterminate: boolean,
) {
const safeMax = max > 0 ? max : 100;
const isIndeterminate = indeterminate || value == null;
const current = isIndeterminate ? 0 : Math.min(safeMax, Math.max(0, value ?? 0));
const fraction = clamp01(current / safeMax);
const percent = Math.round(fraction * 100);
return { safeMax, isIndeterminate, current, fraction, percent };
}
/* -------------------------------------------------------------------------- */
/* Progress */
/* -------------------------------------------------------------------------- */
const TRACK_SIZE: Record<ProgressSize, string> = {
sm: "h-1",
md: "h-2",
lg: "h-3",
};
export interface ProgressProps extends ProgressCommonProps {
size?: ProgressSize;
/** Classes for the fill (e.g. `bg-emerald-500`). */
indicatorClassName?: string;
/** Classes for the track. */
trackClassName?: string;
}
/**
* Linear progress bar. The fill is an HTML element scaled on X from its left
* edge (transform only), smoothed by a critically damped spring.
*/
export function Progress({
value,
max = 100,
indeterminate = false,
label,
showValue = false,
size = "md",
getValueText = defaultValueText,
indicatorClassName,
trackClassName,
className,
"aria-label": ariaLabel,
}: ProgressProps) {
const reduce = useReducedMotion();
const labelId = useId();
const { safeMax, isIndeterminate, current, fraction, percent } =
useProgressState(value, max, indeterminate);
const scaleX = useFraction(fraction);
const hasHeader = label != null || (showValue && !isIndeterminate);
return (
<div
role="progressbar"
aria-label={ariaLabel ?? (typeof label === "string" ? label : undefined)}
aria-labelledby={ariaLabel == null && label != null && typeof label !== "string" ? labelId : undefined}
aria-valuemin={0}
aria-valuemax={safeMax}
aria-valuenow={isIndeterminate ? undefined : current}
aria-valuetext={
isIndeterminate ? undefined : getValueText(percent, current, safeMax)
}
className={cn("flex w-full flex-col gap-2", className)}
>
{hasHeader ? (
<div className="flex items-baseline justify-between gap-3 text-sm">
{label != null ? (
<span id={labelId} className="min-w-0 truncate font-medium text-foreground">
{label}
</span>
) : (
<span />
)}
{showValue && !isIndeterminate ? (
<span aria-hidden="true" className="shrink-0 text-muted-foreground">
<NumberTicker
value={percent}
suffix="%"
startOnView={false}
duration={0.45}
stagger={0}
/>
</span>
) : null}
</div>
) : null}
<div
className={cn(
"relative w-full overflow-hidden rounded-full bg-foreground/10",
TRACK_SIZE[size],
trackClassName,
)}
>
{isIndeterminate ? (
reduce ? (
<motion.div
className={cn("absolute inset-0 rounded-full bg-primary", indicatorClassName)}
animate={REDUCED_PULSE.animate}
transition={REDUCED_PULSE.transition}
/>
) : (
// A 40%-wide segment travels from fully off the left edge
// (-100% of itself) to fully off the right (250% of itself).
<motion.div
className={cn(
"absolute inset-y-0 left-0 w-2/5 rounded-full bg-primary",
indicatorClassName,
)}
initial={{ x: "-100%" }}
animate={{ x: "250%" }}
transition={{ duration: 1.4, ease: EASE_IN_OUT, repeat: Infinity }}
/>
)
) : (
<motion.div
className={cn(
"absolute inset-0 origin-left rounded-full bg-primary",
indicatorClassName,
)}
style={{ scaleX }}
/>
)}
</div>
</div>
);
}
/* -------------------------------------------------------------------------- */
/* ProgressCircle */
/* -------------------------------------------------------------------------- */
export interface ProgressCircleProps extends ProgressCommonProps {
/** Diameter in px. */
size?: number;
/** Stroke width in px. */
thickness?: number;
/** Replace the centered percentage with custom content. */
children?: ReactNode;
/** Classes for the progress arc (stroke via `text-*`). */
indicatorClassName?: string;
}
/**
* Ring progress. The arc draws with `pathLength`; the 12 o'clock start and
* the indeterminate spin rotate whole HTML/SVG boxes with CSS transforms, so
* no transform-origin is ever set on an inner SVG shape.
*/
export function ProgressCircle({
value,
max = 100,
indeterminate = false,
label,
showValue = true,
size = 64,
thickness,
getValueText = defaultValueText,
children,
indicatorClassName,
className,
"aria-label": ariaLabel,
}: ProgressCircleProps) {
const reduce = useReducedMotion();
const labelId = useId();
const { safeMax, isIndeterminate, current, fraction, percent } =
useProgressState(value, max, indeterminate);
const stroke = thickness ?? Math.max(3, Math.round(size * 0.09));
const r = (size - stroke) / 2;
const c = size / 2;
const pathLength = useFraction(fraction);
// A round cap on a zero-length path still paints a dot; hide it at 0.
const arcOpacity = useTransform(pathLength, (v) => (v > 0.002 ? 1 : 0));
const fontSize = Math.max(10, Math.round(size * 0.22));
const center =
children ??
(showValue && !isIndeterminate ? (
<NumberTicker
value={percent}
suffix="%"
startOnView={false}
duration={0.45}
stagger={0}
className="font-semibold text-foreground"
/>
) : null);
const ring = (
<svg
width={size}
height={size}
viewBox={`0 0 ${size} ${size}`}
aria-hidden="true"
focusable="false"
// Start at 12 o'clock: rotate the whole <svg> box with CSS.
className="-rotate-90"
>
<circle
cx={c}
cy={c}
r={r}
fill="none"
strokeWidth={stroke}
className="stroke-foreground/10"
/>
{isIndeterminate ? (
<motion.circle
cx={c}
cy={c}
r={r}
fill="none"
strokeWidth={stroke}
strokeLinecap="round"
className={cn("stroke-current text-primary", indicatorClassName)}
initial={false}
animate={{ pathLength: 0.28 }}
transition={{ duration: 0 }}
/>
) : (
<motion.circle
cx={c}
cy={c}
r={r}
fill="none"
strokeWidth={stroke}
strokeLinecap="round"
className={cn("stroke-current text-primary", indicatorClassName)}
style={{ pathLength, opacity: arcOpacity }}
/>
)}
</svg>
);
return (
<div
role="progressbar"
aria-label={ariaLabel ?? (typeof label === "string" ? label : undefined)}
aria-labelledby={ariaLabel == null && label != null && typeof label !== "string" ? labelId : undefined}
aria-valuemin={0}
aria-valuemax={safeMax}
aria-valuenow={isIndeterminate ? undefined : current}
aria-valuetext={
isIndeterminate ? undefined : getValueText(percent, current, safeMax)
}
className={cn("inline-flex flex-col items-center gap-2", className)}
>
<div className="relative" style={{ width: size, height: size }}>
{isIndeterminate ? (
// The spin lives on an HTML wrapper, never on an SVG child.
<motion.div
className="size-full"
animate={reduce ? REDUCED_PULSE.animate : { rotate: 360 }}
transition={
reduce
? REDUCED_PULSE.transition
: { duration: 1, ease: "linear", repeat: Infinity }
}
>
{ring}
</motion.div>
) : (
ring
)}
{center != null ? (
<div
aria-hidden="true"
className="absolute inset-0 flex items-center justify-center tabular-nums"
style={{ fontSize }}
>
{center}
</div>
) : null}
</div>
{label != null ? (
<span id={labelId} className="text-xs text-muted-foreground">
{label}
</span>
) : null}
</div>
);
}
/* -------------------------------------------------------------------------- */
/* ProgressSteps */
/* -------------------------------------------------------------------------- */
export type ProgressStep = { label: string };
export interface ProgressStepsProps {
/** Number of segments, or labelled steps (labels render under segments). */
steps: number | ProgressStep[];
/**
* Completed steps. Fractions partially fill the next segment, e.g. `2.5`
* fills two segments and half of the third.
*/
value: number;
size?: ProgressSize;
/** Hide the step labels even when `steps` carries them. */
hideLabels?: boolean;
"aria-label"?: string;
indicatorClassName?: string;
className?: string;
}
// Delay between neighbouring segments so a jump of several steps reads as a
// sequence (stage 1 completes, then stage 2…) instead of all at once.
const SEGMENT_STAGGER = 0.14;
/**
* Segmented progress: N tracks that fill one after another, e.g. upload
* stages or onboarding steps. Increases fill left→right; decreases unwind
* right→left.
*/
export function ProgressSteps({
steps,
value,
size = "md",
hideLabels = false,
indicatorClassName,
className,
"aria-label": ariaLabel = "Progress",
}: ProgressStepsProps) {
const reduce = useReducedMotion();
const list: ProgressStep[] =
typeof steps === "number"
? Array.from({ length: Math.max(1, steps) }, (_, i) => ({ label: `Step ${i + 1}` }))
: steps;
const count = list.length;
const current = Math.min(count, Math.max(0, Number.isFinite(value) ? value : 0));
const showLabels = !hideLabels && typeof steps !== "number";
// Previous value decides the sequence direction and where it starts.
const prevRef = useRef(current);
const from = prevRef.current;
useEffect(() => {
prevRef.current = current;
}, [current]);
const growing = current >= from;
const activeIndex = Math.min(count - 1, Math.floor(current));
const valueText =
current >= count
? `All ${count} steps complete`
: `Step ${activeIndex + 1} of ${count}: ${list[activeIndex]?.label ?? ""}`;
return (
<div
role="progressbar"
aria-label={ariaLabel}
aria-valuemin={0}
aria-valuemax={count}
aria-valuenow={current}
aria-valuetext={valueText}
className={cn("flex w-full flex-col gap-2", className)}
>
<div className="flex w-full gap-1.5">
{list.map((_step, i) => {
const fill = clamp01(current - i);
const order = growing
? Math.max(0, i - Math.floor(from))
: Math.max(0, Math.ceil(from) - 1 - i);
return (
<div
// biome-ignore lint/suspicious/noArrayIndexKey: segments are positional and never reorder
key={i}
className={cn(
"relative flex-1 overflow-hidden rounded-full bg-foreground/10",
TRACK_SIZE[size],
)}
>
<motion.div
className={cn(
"absolute inset-0 origin-left rounded-full bg-primary",
indicatorClassName,
)}
initial={false}
animate={{ scaleX: fill }}
transition={
reduce
? { duration: 0 }
: { duration: 0.32, ease: EASE_OUT, delay: order * SEGMENT_STAGGER }
}
/>
</div>
);
})}
</div>
{showLabels ? (
<div aria-hidden="true" className="flex w-full gap-1.5">
{list.map((step, i) => (
<span
// biome-ignore lint/suspicious/noArrayIndexKey: segments are positional and never reorder
key={i}
className={cn(
"min-w-0 flex-1 truncate text-xs transition-colors duration-200",
i < current ? "text-foreground" : "text-muted-foreground",
)}
>
{step.label}
</span>
))}
</div>
) : null}
</div>
);
}
"use client";
import {
AnimatePresence,
type HTMLMotionProps,
motion,
useReducedMotion,
} from "motion/react";
import {
forwardRef,
type PointerEvent,
type ReactNode,
useCallback,
useRef,
useState,
} from "react";
import { EASE_OUT, SPRING_PRESS } from "@/lib/ease";
import { useHoverCapable } from "@/lib/hooks/use-hover-capable";
import { TOUCH_TARGET_CLASS } from "@/lib/touch";
import { cn } from "@/lib/utils";
export type ButtonVariant = "primary" | "secondary" | "ghost" | "outline";
export type ButtonSize = "sm" | "md" | "lg" | "icon";
export interface ButtonProps extends Omit<
HTMLMotionProps<"button">,
"children"
> {
variant?: ButtonVariant;
size?: ButtonSize;
pressScale?: number;
/** Spawn a Material-style ripple from the press point. Off by default. */
ripple?: boolean;
children?: ReactNode;
}
export interface ButtonLinkProps extends Omit<
HTMLMotionProps<"a">,
"children"
> {
variant?: ButtonVariant;
size?: ButtonSize;
pressScale?: number;
children?: ReactNode;
}
type Ripple = { id: number; x: number; y: number; size: number };
const VARIANT_CLASS: Record<ButtonVariant, string> = {
primary: "bg-primary text-primary-foreground hover:bg-primary/90",
secondary: "border border-border bg-card text-foreground hover:border-border",
ghost: "text-muted-foreground hover:text-foreground hover:bg-primary/5",
outline:
"border border-border bg-transparent text-foreground hover:bg-primary/5",
};
const SIZE_CLASS: Record<ButtonSize, string> = {
sm: "h-8 px-3 text-xs gap-1.5 rounded-full",
md: "h-10 px-5 text-sm gap-2 rounded-full",
lg: "h-12 px-6 text-base gap-2 rounded-full",
icon: "h-8 w-8 rounded-lg",
};
export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
function Button(
{
variant = "primary",
size = "md",
pressScale = 0.93,
ripple = false,
className,
children,
onPointerDown,
...rest
},
ref,
) {
const reduce = useReducedMotion();
const canHover = useHoverCapable();
const [ripples, setRipples] = useState<Ripple[]>([]);
const nextId = useRef(0);
const handlePointerDown = useCallback(
(event: PointerEvent<HTMLButtonElement>) => {
if (ripple && !reduce) {
const rect = event.currentTarget.getBoundingClientRect();
const size = Math.max(rect.width, rect.height) * 2;
const id = nextId.current++;
setRipples((prev) => [
...prev,
{
id,
x: event.clientX - rect.left,
y: event.clientY - rect.top,
size,
},
]);
}
onPointerDown?.(event);
},
[ripple, reduce, onPointerDown],
);
return (
<motion.button
ref={ref}
type="button"
whileTap={reduce ? undefined : { scale: pressScale }}
whileHover={reduce || !canHover ? undefined : { scale: 1.02 }}
transition={SPRING_PRESS}
onPointerDown={handlePointerDown}
className={cn(
"relative inline-flex items-center justify-center font-medium select-none",
"transition-colors",
"disabled:pointer-events-none disabled:opacity-50",
// The ripple layer clips itself, so on a touch screen the button can
// stop clipping and let its enlarged hit area overhang.
ripple && "overflow-hidden pointer-coarse:overflow-visible",
TOUCH_TARGET_CLASS,
VARIANT_CLASS[variant],
SIZE_CLASS[size],
className,
)}
{...rest}
>
{ripple && !reduce ? (
<span className="pointer-events-none absolute inset-0 overflow-hidden rounded-[inherit]">
<AnimatePresence>
{ripples.map((r) => (
<motion.span
key={r.id}
className="absolute rounded-full bg-current"
style={{
left: r.x,
top: r.y,
width: r.size,
height: r.size,
x: "-50%",
y: "-50%",
}}
initial={{ scale: 0.05, opacity: 0.3 }}
animate={{ scale: 1, opacity: 0 }}
exit={{ opacity: 0 }}
transition={{ duration: 1.6, ease: EASE_OUT }}
onAnimationComplete={() =>
setRipples((prev) => prev.filter((x) => x.id !== r.id))
}
/>
))}
</AnimatePresence>
</span>
) : null}
{children}
</motion.button>
);
},
);
export const ButtonLink = forwardRef<HTMLAnchorElement, ButtonLinkProps>(
function ButtonLink(
{
variant = "primary",
size = "md",
pressScale = 0.93,
className,
children,
...rest
},
ref,
) {
const reduce = useReducedMotion();
const canHover = useHoverCapable();
return (
<motion.a
ref={ref}
whileTap={reduce ? undefined : { scale: pressScale }}
whileHover={reduce || !canHover ? undefined : { scale: 1.02 }}
transition={SPRING_PRESS}
className={cn(
"relative inline-flex items-center justify-center font-medium select-none",
"transition-colors",
TOUCH_TARGET_CLASS,
VARIANT_CLASS[variant],
SIZE_CLASS[size],
className,
)}
{...rest}
>
{children}
</motion.a>
);
},
);
"use client";
import { forwardRef } from "react";
import { Magnetic } from "../magnetic";
import { Button, type ButtonProps } from "./base";
export interface MagneticButtonProps extends ButtonProps {
/** Magnetic pull strength. Default 0.25. */
strength?: number;
/** Class applied to the magnetic wrapper. */
magneticClassName?: string;
}
export const MagneticButton = forwardRef<HTMLButtonElement, MagneticButtonProps>(function MagneticButton(
{ strength = 0.25, magneticClassName, children, ...rest },
ref,
) {
return (
<Magnetic strength={strength} className={magneticClassName}>
<Button ref={ref} {...rest}>
{children}
</Button>
</Magnetic>
);
});
"use client";
import { Check, Loader2, X } from "lucide-react";
import {
AnimatePresence,
motion,
useReducedMotion,
type Variants,
} from "motion/react";
import {
forwardRef,
type ReactNode,
useLayoutEffect,
useRef,
useState,
} from "react";
import { EASE_OUT, SPRING_SWAP } from "@/lib/ease";
import { Button, type ButtonProps } from "./base";
export type ButtonState = "idle" | "loading" | "success" | "error";
export interface StatefulButtonProps extends Omit<ButtonProps, "children"> {
state?: ButtonState;
children: ReactNode;
loadingText?: ReactNode;
successText?: ReactNode;
errorText?: ReactNode;
icon?: ReactNode;
}
const CASCADE_STAGGER = 0.025;
const ROLL_BLUR = "blur(6px)";
const CASCADE_LETTER_VARIANTS: Variants = {
initial: { opacity: 0, y: "105%", filter: ROLL_BLUR },
animate: (delay: number = 0) => ({
opacity: 1,
y: "0%",
filter: "blur(0px)",
transition: { ...SPRING_SWAP, delay },
}),
exit: (delay: number = 0) => ({
opacity: 0,
y: "-105%",
filter: ROLL_BLUR,
transition: { duration: 0.16, ease: EASE_OUT, delay: delay * 0.5 },
}),
};
const ICON_VARIANTS: Variants = {
// Width collapses too, so the icon adds/removes its own space smoothly
// instead of popping the row width in a single frame.
initial: { opacity: 0, width: 0, scale: 0.7, filter: ROLL_BLUR },
animate: {
opacity: 1,
width: "1.5rem",
scale: 1,
filter: "blur(0px)",
transition: SPRING_SWAP,
},
exit: {
opacity: 0,
width: 0,
scale: 0.7,
filter: ROLL_BLUR,
transition: { duration: 0.16, ease: EASE_OUT },
},
};
function IconSlot({ keyId, children }: { keyId: string; children: ReactNode }) {
const reduce = useReducedMotion();
return (
<motion.span
key={keyId}
variants={ICON_VARIANTS}
initial={reduce ? { opacity: 0 } : "initial"}
animate={reduce ? { opacity: 1 } : "animate"}
exit={reduce ? { opacity: 0 } : "exit"}
transition={reduce ? { duration: 0.15 } : undefined}
className="inline-grid shrink-0 place-items-center overflow-hidden"
>
{children}
</motion.span>
);
}
function TextSlot({
value,
children,
}: {
value: string;
children: ReactNode;
}) {
const reduce = useReducedMotion();
const measureRef = useRef<HTMLSpanElement>(null);
const [width, setWidth] = useState<number>();
const label = typeof children === "string" ? children : null;
const cascade = label !== null && !reduce;
// Measure strings with the same per-letter layout as the cascade. Measuring
// the whole string preserves kerning, which can make it narrower than the
// inline-block letters and clip the final glyph during the width animation.
useLayoutEffect(() => {
const nextWidth = measureRef.current?.offsetWidth;
if (!nextWidth) return;
setWidth((current) => (current === nextWidth ? current : nextWidth));
});
return (
<motion.span
initial={false}
animate={{ width }}
transition={reduce ? { duration: 0 } : SPRING_SWAP}
className="relative inline-block overflow-hidden whitespace-nowrap align-bottom"
>
<span
ref={measureRef}
aria-hidden
className="invisible inline-block whitespace-nowrap"
>
{cascade
? label.split("").map((char, index) => (
<span
// biome-ignore lint/suspicious/noArrayIndexKey: position is the slot identity.
key={index}
className="inline-block whitespace-pre"
>
{char}
</span>
))
: children}
</span>
{cascade ? (
<>
<span className="sr-only">{label}</span>
<AnimatePresence initial={false}>
<motion.span
key={`cascade-${value}`}
aria-hidden
initial="initial"
animate="animate"
exit="exit"
className="absolute left-0 top-0 inline-block whitespace-pre"
>
{label.split("").map((char, index) => (
<motion.span
// biome-ignore lint/suspicious/noArrayIndexKey: position is the slot identity.
key={index}
custom={index * CASCADE_STAGGER}
variants={CASCADE_LETTER_VARIANTS}
className="inline-block whitespace-pre will-change-[opacity,filter,transform]"
>
{char}
</motion.span>
))}
</motion.span>
</AnimatePresence>
</>
) : (
<AnimatePresence initial={false}>
<motion.span
key={`text-${value}`}
initial={reduce ? { opacity: 0 } : { opacity: 0, y: 14, filter: ROLL_BLUR }}
animate={reduce ? { opacity: 1 } : { opacity: 1, y: 0, filter: "blur(0px)" }}
exit={reduce ? { opacity: 0 } : { opacity: 0, y: -14, filter: ROLL_BLUR }}
transition={reduce ? { duration: 0.15 } : SPRING_SWAP}
className="absolute left-0 top-0 inline-block will-change-[opacity,filter,transform]"
>
{children}
</motion.span>
</AnimatePresence>
)}
</motion.span>
);
}
export const StatefulButton = forwardRef<HTMLButtonElement, StatefulButtonProps>(function StatefulButton(
{
state = "idle",
children,
loadingText = "Loading",
successText = "Done",
errorText = "Try again",
icon,
disabled,
...rest
},
ref,
) {
const isBusy = state === "loading";
const stateText =
state === "loading"
? loadingText
: state === "success"
? successText
: state === "error"
? errorText
: children;
const textKey =
typeof stateText === "string" ? `${state}-${stateText}` : state;
return (
<Button ref={ref} disabled={disabled || isBusy} aria-busy={isBusy} whileHover={undefined} {...rest}>
<span
aria-live="polite"
className="relative inline-flex items-center justify-center overflow-hidden"
>
<AnimatePresence initial={false}>
{state === "loading" ? (
<IconSlot keyId="loading-icon">
<Loader2 className="h-4 w-4 animate-spin" />
</IconSlot>
) : null}
{state === "success" ? (
<IconSlot keyId="success-icon">
<Check className="h-4 w-4" />
</IconSlot>
) : null}
{state === "error" ? (
<IconSlot keyId="error-icon">
<X className="h-4 w-4" />
</IconSlot>
) : null}
</AnimatePresence>
<TextSlot value={textKey}>{stateText}</TextSlot>
<AnimatePresence initial={false}>
{state === "idle" && icon ? (
<IconSlot keyId="idle-icon">{icon}</IconSlot>
) : null}
</AnimatePresence>
</span>
</Button>
);
});
"use client";
import { animate, motion, useInView, useReducedMotion } from "motion/react";
import { useEffect, useMemo, useRef, useState } from "react";
import { EASE_OUT } from "@/lib/ease";
import { cn } from "@/lib/utils";
export interface NumberTickerProps {
value: number;
/** Digits to pad to (left). */
pad?: number;
/** Per-digit roll duration in seconds. */
duration?: number;
/** Stagger between digits. */
stagger?: number;
/** Render only after the element enters the viewport. */
startOnView?: boolean;
prefix?: string;
suffix?: string;
/** Add a small blur during digit rolls. */
blur?: boolean;
className?: string;
digitClassName?: string;
/** Insert en-US group separators (commas); fixed so server and client match. Server-component safe. */
locale?: boolean;
/** Custom formatter. Client-only — server components must use `locale` instead. */
format?: (value: number) => string;
}
const DIGIT_HEIGHT_EM = 1.1;
const DIGITS = Array.from({ length: 10 }, (_, n) => n);
export function NumberTicker({
value,
pad,
duration = 0.9,
stagger = 0.04,
startOnView = true,
prefix,
suffix,
blur = false,
className,
digitClassName,
locale,
format,
}: NumberTickerProps) {
const containerRef = useRef<HTMLSpanElement>(null);
const inView = useInView(containerRef, { once: true, amount: 0.6 });
const [armed, setArmed] = useState(!startOnView);
useEffect(() => {
if (startOnView && inView) setArmed(true);
}, [startOnView, inView]);
const text = useMemo(() => {
const rounded = Math.round(value);
const formatted = format
? format(rounded)
: locale
? rounded.toLocaleString("en-US")
: rounded.toString();
return pad ? formatted.padStart(pad, "0") : formatted;
}, [value, pad, format, locale]);
const glyphs = useMemo(() => {
const chars = text.split("");
// Key by place value (position from the right): a changing digit keeps its
// identity and rolls to the new value instead of remounting and replaying
// from 0. Growing numbers add glyphs on the left without re-keying the
// ones, tens, hundreds already on screen.
return chars.map((char, i) => ({ char, id: `g-${chars.length - 1 - i}` }));
}, [text]);
const readableText = `${prefix ?? ""}${text}${suffix ?? ""}`;
// Stagger is an entrance flourish. Once the reveal has played, value
// changes roll every digit immediately — a per-digit delay on live updates
// reads as lag.
const [entered, setEntered] = useState(false);
useEffect(() => {
if (!armed || entered) return;
const total = (duration + glyphs.length * stagger) * 1000;
const t = window.setTimeout(() => setEntered(true), total);
return () => window.clearTimeout(t);
}, [armed, entered, duration, stagger, glyphs.length]);
return (
<span
ref={containerRef}
className={cn("inline-flex items-center tabular-nums", className)}
>
<span className="sr-only">{readableText}</span>
<span aria-hidden="true" className="inline-flex items-center">
{prefix ? <span>{prefix}</span> : null}
{glyphs.map(({ char, id }, i) => {
const isDigit = /\d/.test(char);
if (!isDigit) {
return (
<span key={id} className="inline-block">
{char}
</span>
);
}
const digit = Number(char);
return (
<Digit
key={id}
digit={armed ? digit : 0}
delay={entered ? 0 : i * stagger}
duration={duration}
blur={blur}
className={digitClassName}
/>
);
})}
{suffix ? <span>{suffix}</span> : null}
</span>
</span>
);
}
function Digit({
digit,
delay,
duration,
blur,
className,
}: {
digit: number;
delay: number;
duration: number;
blur: boolean;
className?: string;
}) {
const reduce = useReducedMotion();
const columnRef = useRef<HTMLSpanElement>(null);
useEffect(() => {
if (reduce || !blur || !columnRef.current || !Number.isFinite(digit)) {
return;
}
const node = columnRef.current;
const controls = animate(
node,
{ filter: ["blur(10px)", "blur(0px)"] },
{
duration: Math.min(duration * 0.75, 0.32),
delay,
ease: EASE_OUT,
},
);
return () => {
controls.stop();
node.style.filter = "blur(0px)";
};
}, [blur, delay, digit, duration, reduce]);
return (
<span
className={cn("relative inline-block overflow-hidden", className)}
style={{ height: `${DIGIT_HEIGHT_EM}em`, width: "1ch" }}
>
<motion.span
ref={columnRef}
initial={{ y: 0 }}
animate={{ y: `-${digit * DIGIT_HEIGHT_EM}em` }}
transition={
reduce
? { duration: 0 }
: { duration, delay, ease: EASE_OUT }
}
className="absolute inset-x-0 top-0 flex flex-col items-center will-change-[transform,filter]"
>
{DIGITS.map((n) => (
<span
key={n}
className="flex h-[1.1em] items-center justify-center leading-none"
>
{n}
</span>
))}
</motion.span>
</span>
);
}
"use client";
import { motion, useMotionValue, useReducedMotion, useSpring } from "motion/react";
import { useRef, type ReactNode } from "react";
import { SPRING_MOUSE } from "@/lib/ease";
import { useHoverCapable } from "@/lib/hooks/use-hover-capable";
import { cn } from "@/lib/utils";
export interface MagneticProps {
children: ReactNode;
strength?: number;
className?: string;
}
export function Magnetic({ children, strength = 0.35, className }: MagneticProps) {
const ref = useRef<HTMLDivElement>(null);
const reduce = useReducedMotion();
const canHover = useHoverCapable();
// Decorative cursor-follow: skip on touch (phantom hover) and reduced motion.
const enabled = !reduce && canHover;
const x = useMotionValue(0);
const y = useMotionValue(0);
const sx = useSpring(x, SPRING_MOUSE);
const sy = useSpring(y, SPRING_MOUSE);
const onMove = (e: React.MouseEvent<HTMLDivElement>) => {
const el = ref.current;
if (!el || !enabled) return;
const rect = el.getBoundingClientRect();
x.set((e.clientX - rect.left - rect.width / 2) * strength);
y.set((e.clientY - rect.top - rect.height / 2) * strength);
};
const onLeave = () => {
x.set(0);
y.set(0);
};
return (
<motion.div
ref={ref}
onMouseMove={onMove}
onMouseLeave={onLeave}
style={{ x: sx, y: sy }}
className={cn("inline-block", className)}
>
{children}
</motion.div>
);
}
@karaui not found? Add it to components.json
{
"registries": {
"@karaui": "https://karaui.kamisama-v0.my.id/r/{name}.json"
}
}@karaui is in shadcn's public registry directory, so the latest CLI needs no setup. On an older CLI, merge this into the existing file once and every @karaui/… install resolves.
API Reference
stepsOnboardingStep[]—completed?string[]Controlled completed step ids.
—defaultCompleted?string[][]onCompletedChange?((completed: string[]) => void)—open?booleanControlled visibility. Dismissing sets it to false.
—defaultOpen?booleantrueonOpenChange?((open: boolean) => void)—dismissible?booleantruetitle?ReactNodeGet starteddescription?ReactNodeA few steps to set up your workspace.celebrationTitle?ReactNodeYou're all set!celebrationDescription?ReactNodeYour workspace is ready. Time to build something.className?string—Keep in mind
Some components on this site are inspired by or recreated from existing work across the web. I'm not here to take credit; just to learn, experiment, and sometimes push things a bit further. If something looks familiar and I forgot to mention you, reach out and I'll fix that right away.
Updated