{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "stepper", "type": "registry:ui", "title": "Stepper", "description": "An accessible React stepper for Next.js and Tailwind CSS: the steps of a checkout or setup, with a line that fills as you advance and checks that draw in.", "author": "FewTone ", "dependencies": [ "motion@^14.0.0", "radix-ui@^1.7.0" ], "registryDependencies": [ "https://ui.fewtone.com/r/tokens.json", "https://ui.fewtone.com/r/motion.json" ], "files": [ { "path": "registry/fewtone/ui/stepper.tsx", "type": "registry:ui", "content": "\"use client\";\n\nimport { blur, duration, ease } from \"@/lib/motion\";\nimport { cn } from \"@/lib/utils\";\nimport { motion, useReducedMotion } from \"motion/react\";\nimport { Slot } from \"radix-ui\";\nimport {\n type ComponentProps,\n createContext,\n type MouseEvent,\n useCallback,\n useContext,\n useEffect,\n useMemo,\n useState,\n} from \"react\";\n\n/*\n * Stepper: progress through the steps of a task (owner's roadmap, 2026-10-16), such as a checkout or a setup.\n * shadcn has none, so the parts are ours, named the shadcn way: Stepper (an ordered list), StepperItem,\n * StepperTrigger, StepperIndicator, StepperTitle, StepperDescription and StepperSeparator.\n * - State: `value` is the current step, from 1; the steps before it are completed, and a value past the last\n * step marks them all done. Controlled or not (value / defaultValue / onValueChange), horizontal or vertical.\n * - Motion (the crafted part, .agents/rules/motion.md): progress travels along the line. Moving on, the step you\n * leave swaps its number for a check that draws itself in (Checkbox's check), the line to the next step fills\n * (scaleX, or scaleY when vertical, on an eased tween: duration.slow, ease-in-out, never a spring), and the next\n * step takes the ring as the fill arrives. Jumping several steps fills each line in turn. Going back plays it\n * backwards: the ring leaves, the lines empty towards the step you picked, and as the emptying reaches it, its\n * check erases and its number comes back through the blur.\n * - Fills and colours only fade; the number comes and goes through the blur; the ring grows into place as it\n * fades in. Nothing moves on first paint, and with reduced motion it all changes at once.\n * - Keyboard and screen readers: each step is a button (or, with asChild, a link) in the tab order, named by its\n * title; the current one has aria-current=\"step\". It's an `ol`, so it's read as a list of so many steps.\n */\n\ntype StepState = \"completed\" | \"active\" | \"inactive\";\ntype Orientation = \"horizontal\" | \"vertical\";\n\n/** One line's fill. Each step along the way waits for the line before it. */\nconst LEG = duration.slow;\n\ntype StepperContextValue = {\n value: number;\n /** The step the last change came from, while its progress is still travelling; then the same as value */\n from: number;\n orientation: Orientation;\n reduce: boolean;\n setValue: (step: number) => void;\n};\nconst StepperContext = createContext(null);\n\nfunction useStepper(part: string) {\n const context = useContext(StepperContext);\n if (!context) throw new Error(`${part} must be used inside Stepper`);\n return context;\n}\n\ntype StepperItemContextValue = {\n step: number;\n state: StepState;\n disabled: boolean;\n /** Seconds until this step's indicator changes: when the travelling progress reaches it */\n delay: number;\n /** Seconds until the line after this step starts filling or emptying */\n lineDelay: number;\n};\nconst StepperItemContext = createContext(null);\n\nfunction useStepperItem(part: string) {\n const context = useContext(StepperItemContext);\n if (!context) throw new Error(`${part} must be used inside StepperItem`);\n return context;\n}\n\n/** A number of legs, in seconds (to the millisecond, so 3 × 0.35 is 1.05) */\nconst legs = (count: number) => Math.round(count * LEG * 1000) / 1000;\n\n/** When a step changes and when the line after it moves, as progress travels from `from` to `to` */\nfunction timingOf(step: number, from: number, to: number) {\n if (to > from) {\n return {\n delay: step >= from && step <= to ? legs(step - from) : 0,\n lineDelay: step >= from && step < to ? legs(step - from) : 0,\n };\n }\n if (to < from) {\n return {\n delay: step >= to && step <= from ? legs(from - step) : 0,\n lineDelay: step >= to && step < from ? legs(from - 1 - step) : 0,\n };\n }\n return { delay: 0, lineDelay: 0 };\n}\n\nexport type StepperProps = Omit, \"defaultValue\" | \"onChange\"> & {\n /** The current step, from 1, when you control it. Past the last step, every step is done */\n value?: number;\n /** The current step at first */\n defaultValue?: number;\n /** Called with the step a trigger was pressed for */\n onValueChange?: (value: number) => void;\n orientation?: Orientation;\n};\n\n/** The steps of a task, in order. Give it a name with aria-label (\"Checkout\") */\nfunction Stepper({\n value,\n defaultValue = 1,\n onValueChange,\n orientation = \"horizontal\",\n className,\n ...props\n}: StepperProps) {\n const [uncontrolled, setUncontrolled] = useState(defaultValue);\n const current = value ?? uncontrolled;\n const reduce = useReducedMotion() ?? false;\n // Where the last change came from, so progress can travel from there. Once it has arrived, `from` catches up\n // and every delay is 0 again, so hovering a step never waits.\n const [shown, setShown] = useState(current);\n const [from, setFrom] = useState(current);\n if (current !== shown) {\n setShown(current);\n setFrom(shown);\n }\n useEffect(() => {\n if (from === current) return;\n const timer = setTimeout(() => setFrom(current), (Math.abs(current - from) + 1) * LEG * 1000);\n return () => clearTimeout(timer);\n }, [from, current]);\n\n const setValue = useCallback(\n (step: number) => {\n if (value === undefined) setUncontrolled(step);\n onValueChange?.(step);\n },\n [value, onValueChange],\n );\n const context = useMemo(\n () => ({ value: current, from: reduce ? current : from, orientation, reduce, setValue }),\n [current, from, orientation, reduce, setValue],\n );\n\n return (\n \n \n \n );\n}\n\nexport type StepperItemProps = ComponentProps<\"li\"> & {\n /** Its place in the task, from 1 */\n step: number;\n /** Done (true) or not (false), whatever the current step. Left out, the steps before the current one are done */\n completed?: boolean;\n /** Its trigger can't be pressed, for example a step that isn't reachable yet */\n disabled?: boolean;\n};\n\n/** One step. Holds its trigger and the separator to the next step */\nfunction StepperItem({ step, completed, disabled = false, className, ...props }: StepperItemProps) {\n const { value, from, orientation } = useStepper(\"StepperItem\");\n const state: StepState = (completed ?? step < value) ? \"completed\" : step === value ? \"active\" : \"inactive\";\n const { delay, lineDelay } = timingOf(step, from, value);\n const item = useMemo(\n () => ({ step, state, disabled, delay, lineDelay }),\n [step, state, disabled, delay, lineDelay],\n );\n\n return (\n \n \n \n );\n}\n\nexport type StepperTriggerProps = ComponentProps<\"button\"> & {\n /** Render the single child instead of a button, for example a link to the step's page */\n asChild?: boolean;\n};\n\n/**\n * Goes to its step. Holds the indicator, the title and the description, laid out in two columns. The current\n * step's trigger has aria-current=\"step\".\n */\nfunction StepperTrigger({ className, asChild = false, onClick, style, ...props }: StepperTriggerProps) {\n const { setValue, reduce } = useStepper(\"StepperTrigger\");\n const { step, state, disabled, delay } = useStepperItem(\"StepperTrigger\");\n const Comp = asChild ? Slot.Root : \"button\";\n\n return (\n ) => {\n onClick?.(event);\n if (event.defaultPrevented) return;\n if (disabled) {\n // A disabled link mustn't navigate either\n event.preventDefault();\n return;\n }\n setValue(step);\n }}\n className={cn(\n // Two columns: the indicator, spanning both rows, then the title over the description\n \"group/trigger grid cursor-pointer items-start justify-items-start gap-x-2 rounded-md text-start\",\n \"transition-opacity duration-(--duration-base) ease-out\",\n \"outline-ring focus-visible:outline-(length:--focus-ring-width) focus-visible:outline-offset-(--focus-ring-offset)\",\n \"disabled:pointer-events-none disabled:opacity-(--opacity-disabled) aria-disabled:pointer-events-none aria-disabled:opacity-(--opacity-disabled)\",\n className,\n )}\n // A step that becomes reachable brightens as the progress arrives\n style={{ transitionDelay: `${reduce ? 0 : delay}s`, ...style }}\n {...props}\n />\n );\n}\n\n/** The same check as Checkbox, Copy Button and Loading Button */\nconst CHECK = \"M5 12.5l4.5 4.5L19 7.5\";\n\nexport type StepperIndicatorProps = ComponentProps<\"span\">;\n\n/**\n * The step's circle: its number, a check once it's done, and a ring round the current one. Pass children (an\n * icon) to show them instead of the number and the check. Hidden from screen readers: the title names the step.\n */\nfunction StepperIndicator({ className, children, style, ...props }: StepperIndicatorProps) {\n const { reduce } = useStepper(\"StepperIndicator\");\n const { step, state, delay } = useStepperItem(\"StepperIndicator\");\n const done = state === \"completed\";\n const active = state === \"active\";\n const wait = reduce ? 0 : delay;\n\n return (\n svg]:size-3.5\",\n className,\n )}\n style={{ transitionDelay: `${wait}s`, ...style }}\n {...props}\n >\n {/* The ring round the current step grows into place as it fades in */}\n \n {children ?? (\n <>\n {/* The number lifts away through the blur as the check draws in, and comes back the same way */}\n