{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "multi-step-form", "type": "registry:ui", "title": "Multi-step Form", "description": "Steps slide the way you travel, validate one at a time, and keep every answer.", "categories": [ "forms" ], "dependencies": [ "@base-ui/react", "@number-flow/react", "motion" ], "registryDependencies": [ "https://www.stealth.pm/r/tokens.json", "https://www.stealth.pm/r/cn.json", "https://www.stealth.pm/r/icons.json", "https://www.stealth.pm/r/motion.json", "https://www.stealth.pm/r/use-controllable-state.json" ], "files": [ { "path": "components/ui/multi-step-form.tsx", "content": "\"use client\";\nimport { Form } from \"@base-ui/react/form\";\nimport NumberFlow from \"@number-flow/react\";\nimport { AnimatePresence, animate, motion, useMotionValue, useReducedMotion, useTransform, type AnimationPlaybackControls } from \"motion/react\";\nimport { createContext, useCallback, useContext, useEffect, useLayoutEffect, useRef, useState } from \"react\";\nimport { cn } from \"@/lib/cn\";\nimport { ArrowLeft, Pencil } from \"@/lib/icons\";\nimport { ease, spring } from \"@/lib/motion\";\nimport { useControllableState } from \"@/lib/use-controllable-state\";\n\nexport type MultiStepFormStepDef = {\n id: string;\n /** The step's heading. */\n title: string;\n /** A shorter name for the progress track, e.g. \"Team\" for \"Invite your team\". */\n label?: string;\n description?: string;\n};\nexport type MultiStepFormValues = Record;\ntype Status = \"idle\" | \"checking\" | \"submitting\" | \"done\" | \"error\";\ntype ContinueHandler = (values: MultiStepFormValues) => boolean | void | Promise;\n\ntype Ctx = {\n steps: MultiStepFormStepDef[];\n index: number;\n furthest: number;\n returnTo: number | null;\n status: Status;\n values: MultiStepFormValues;\n labels: Required;\n requestStep: (i: number) => void;\n back: () => void;\n edit: (id: string) => void;\n registerStep: (id: string, el: HTMLElement | null) => void;\n registerHandler: (id: string, fn: ContinueHandler | undefined) => void;\n stepEl: (i: number) => HTMLElement | undefined;\n takeFocus: () => boolean;\n};\nconst MultiStepContext = createContext(null);\n\n/** The form's state, for parts you compose yourself (a custom review, a step counter). */\nexport function useMultiStepForm() {\n const ctx = useContext(MultiStepContext);\n if (!ctx) throw new Error(\"useMultiStepForm must be used inside \");\n return ctx;\n}\n\nexport type MultiStepFormLabels = {\n back?: string;\n continue?: string;\n backToReview?: string;\n submit?: string;\n submitting?: string;\n done?: string;\n error?: string;\n};\n\nexport type MultiStepFormProps = Omit, \"onSubmit\" | \"children\"> & {\n steps: MultiStepFormStepDef[];\n /** The current step's id, when you control it. */\n step?: string;\n defaultStep?: string;\n onStepChange?: (id: string) => void;\n /** Runs after every step validates. Return or resolve to finish; throw to show the error line. */\n onComplete?: (values: MultiStepFormValues) => void | Promise;\n labels?: MultiStepFormLabels;\n children: React.ReactNode;\n};\n\nconst defaultLabels: Required = {\n back: \"Back\",\n continue: \"Continue\",\n backToReview: \"Back to review\",\n submit: \"Submit\",\n submitting: \"Submitting…\",\n done: \"Done\",\n error: \"Couldn’t submit. Check your connection and try again.\",\n};\n\n/**\n * One native form across every step. Steps stay mounted (hidden when inactive), so\n * values, touched state and errors survive going back and forth, and the final\n * submit sees every field. Continue validates only the current step's fields.\n */\nexport function MultiStepForm({\n steps,\n step: stepProp,\n defaultStep,\n onStepChange,\n onComplete,\n labels: labelsProp,\n className,\n children,\n ref,\n ...rest\n}: MultiStepFormProps) {\n const [stepId, setStepId] = useControllableState({ value: stepProp, defaultValue: defaultStep ?? steps[0]?.id ?? \"\", onChange: onStepChange });\n const index = Math.max(0, steps.findIndex((s) => s.id === stepId));\n const [furthest, setFurthest] = useState(index);\n const [returnTo, setReturnTo] = useState(null);\n const [status, setStatus] = useState(\"idle\");\n const [values, setValues] = useState({});\n const labels = { ...defaultLabels, ...labelsProp };\n\n const form = useRef(null);\n const actions = useRef(null);\n const stepEls = useRef(new Map());\n const handlers = useRef(new Map());\n const busy = useRef(false);\n const focusNext = useRef(false);\n\n const setFormRef = useCallback(\n (node: HTMLFormElement | null) => {\n form.current = node;\n if (typeof ref === \"function\") ref(node);\n else if (ref) ref.current = node;\n },\n [ref],\n );\n\n const snapshot = useCallback((): MultiStepFormValues => {\n if (!form.current) return {};\n const data = new FormData(form.current);\n const out: MultiStepFormValues = {};\n for (const key of new Set(data.keys())) {\n const all = data.getAll(key);\n out[key] = all.length > 1 ? all : all[0];\n }\n return out;\n }, []);\n\n const go = (i: number) => {\n const target = steps[i];\n if (!target || i === index) return;\n setValues(snapshot());\n setFurthest((f) => Math.max(f, i));\n if (returnTo === i) setReturnTo(null);\n if (status === \"error\") setStatus(\"idle\");\n // Focus follows the step only when the person moved it, never on mount or from props.\n focusNext.current = !!form.current?.contains(document.activeElement);\n setStepId(target.id);\n };\n\n // Validates one step: asks Base UI to show each named field's error, then reads the\n // browser's verdict. Focuses the first invalid control when the step is on screen.\n const validateStep = async (i: number, focus: boolean, withHandler = true) => {\n const def = steps[i];\n const el = def && stepEls.current.get(def.id);\n if (!el) return true;\n const controls = [...el.querySelectorAll(\"input, select, textarea\")].filter(\n (c) => !c.disabled && c.name,\n );\n for (const name of new Set(controls.map((c) => c.name))) actions.current?.validate(name);\n const invalid = controls.find((c) => !c.checkValidity());\n if (invalid) {\n if (focus) {\n invalid.focus();\n if (invalid instanceof HTMLInputElement && /^(text|email|search|tel|url)$/.test(invalid.type)) invalid.select();\n }\n return false;\n }\n const handler = withHandler ? handlers.current.get(def.id) : undefined;\n if (!handler) return true;\n const result = handler(snapshot());\n if (result && typeof (result as Promise).then === \"function\") {\n setStatus(\"checking\");\n try {\n const ok = await result;\n return ok !== false;\n } catch {\n return false;\n } finally {\n setStatus(\"idle\");\n }\n }\n return result !== false;\n };\n\n const advance = async () => {\n if (busy.current || status === \"done\") return;\n busy.current = true;\n try {\n if (!(await validateStep(index, true))) return;\n const last = steps.length - 1;\n if (index < last) {\n go(returnTo ?? index + 1);\n return;\n }\n // Final submit: every earlier step must still hold. Send the person to the first that doesn't.\n for (let i = 0; i < last; i++) {\n // Fields only: each step's own server check already passed when it was left.\n if (!(await validateStep(i, false, false))) {\n go(i);\n return;\n }\n }\n setStatus(\"submitting\");\n try {\n await onComplete?.(snapshot());\n setStatus(\"done\");\n } catch {\n setStatus(\"error\");\n }\n } finally {\n busy.current = false;\n }\n };\n\n const requestStep = async (i: number) => {\n if (i <= index) return go(i);\n if (i > furthest || busy.current) return;\n busy.current = true;\n try {\n if (await validateStep(index, true)) go(i);\n } finally {\n busy.current = false;\n }\n };\n\n // Stable, because steps and content read them inside effects.\n const registerStep = useCallback((id: string, el: HTMLElement | null) => {\n if (el) stepEls.current.set(id, el);\n else stepEls.current.delete(id);\n }, []);\n const registerHandler = useCallback((id: string, fn: ContinueHandler | undefined) => {\n if (fn) handlers.current.set(id, fn);\n else handlers.current.delete(id);\n }, []);\n const stepEl = useCallback((i: number) => (steps[i] ? stepEls.current.get(steps[i].id) : undefined), [steps]);\n const takeFocus = useCallback(() => {\n const f = focusNext.current;\n focusNext.current = false;\n return f;\n }, []);\n\n const ctx: Ctx = {\n steps,\n index,\n furthest,\n returnTo,\n status,\n values,\n labels,\n requestStep: (i) => void requestStep(i),\n back: () => go(index - 1),\n edit: (id) => {\n const i = steps.findIndex((s) => s.id === id);\n if (i < 0) return;\n setReturnTo(index);\n go(i);\n },\n registerStep,\n registerHandler,\n stepEl,\n takeFocus,\n };\n\n return (\n \n {\n e.preventDefault();\n e.stopPropagation();\n void advance();\n }}\n className={cn(\"flex w-full flex-col gap-5\", className)}\n {...rest}\n >\n {children}\n \n \n );\n}\n\nexport type MultiStepFormProgressProps = React.ComponentProps<\"nav\">;\n\n/** Step count, a segmented track that fills as you go, and labels you can press to go back. */\nexport function MultiStepFormProgress({ className, ...rest }: MultiStepFormProgressProps) {\n const { steps, index, furthest, requestStep, status } = useMultiStepForm();\n const reduce = useReducedMotion();\n const locked = status === \"submitting\" || status === \"done\";\n return (\n \n );\n}\n\nexport type MultiStepFormContentProps = React.ComponentProps<\"div\">;\n\n/** Holds the steps. Its height glides between steps while the content slides the way you're going. */\nexport function MultiStepFormContent({ className, children, ...rest }: MultiStepFormContentProps) {\n const { index, stepEl } = useMultiStepForm();\n const reduce = useReducedMotion();\n const box = useRef(null);\n const settled = useRef(0);\n const moving = useRef(null);\n const first = useRef(true);\n\n // At rest the height is auto (errors can grow a step freely); remember it for the next move.\n useEffect(() => {\n const el = box.current;\n if (!el) return;\n const ro = new ResizeObserver(() => {\n if (!moving.current) settled.current = el.offsetHeight;\n });\n ro.observe(el);\n return () => ro.disconnect();\n }, []);\n\n useLayoutEffect(() => {\n const el = box.current;\n const target = stepEl(index);\n if (first.current) {\n first.current = false;\n return;\n }\n if (!el || !target || reduce) return;\n // Interrupted mid-move: start from wherever the height is now.\n const from = moving.current ? el.offsetHeight : settled.current;\n moving.current?.stop();\n const to = target.offsetHeight;\n el.dataset.moving = \"\";\n const controls = animate(el, { height: [from, to] }, { duration: 0.34, ease: ease.inOut });\n moving.current = controls;\n controls.then(() => {\n if (moving.current !== controls) return;\n moving.current = null;\n el.style.height = \"\";\n delete el.dataset.moving;\n settled.current = el.offsetHeight;\n });\n }, [index, stepEl, reduce]);\n\n return (\n
\n {children}\n
\n );\n}\n\nexport type MultiStepFormStepProps = Omit, \"id\"> & {\n id: string;\n /** Runs after the step's fields pass. Return false (or resolve false) to stay, e.g. after a server check. */\n onContinue?: ContinueHandler;\n /** Hide the built-in title and description, when the step renders its own. */\n hideHeader?: boolean;\n};\n\nexport function MultiStepFormStep({ id, onContinue, hideHeader = false, className, children, ...rest }: MultiStepFormStepProps) {\n const ctx = useMultiStepForm();\n const { steps, index, registerStep, registerHandler, takeFocus } = ctx;\n const reduce = useReducedMotion();\n const mine = steps.findIndex((s) => s.id === id);\n const def = steps[mine];\n const active = mine === index;\n const heading = useRef(null);\n\n // Mounted always, displayed only while active or leaving.\n const [shown, setShown] = useState(active);\n if (active && !shown) setShown(true);\n\n useEffect(() => {\n registerHandler(id, onContinue);\n return () => registerHandler(id, undefined);\n }, [id, onContinue, registerHandler]);\n\n useEffect(() => {\n if (active && takeFocus()) heading.current?.focus({ preventScroll: true });\n }, [active, takeFocus]);\n\n const side = mine < index ? -1 : mine > index ? 1 : 0;\n const titleId = `${id}-step-title`;\n\n return (\n registerStep(id, el)}\n aria-labelledby={hideHeader ? undefined : titleId}\n hidden={!shown}\n inert={!active}\n data-state={active ? \"active\" : \"inactive\"}\n initial={false}\n // The same values render on the server and the client; reduced motion only zeroes the travel's duration.\n animate={{ x: side * 28, opacity: active ? 1 : 0, filter: active ? \"blur(0px)\" : \"blur(2px)\" }}\n transition={\n reduce\n ? { duration: 0.15, x: { duration: 0 }, filter: { duration: 0 } }\n : active\n ? { duration: 0.34, ease: ease.out, delay: 0.04 }\n : { duration: 0.2, ease: ease.in }\n }\n onAnimationComplete={() => {\n if (!active) setShown(false);\n }}\n className={cn(\"col-start-1 row-start-1 flex min-w-0 flex-col gap-4 self-start\", className)}\n {...(rest as object)}\n >\n {!hideHeader && def && (\n
\n

\n {def.title}\n

\n {def.description &&

{def.description}

}\n
\n )}\n {children}\n \n );\n}\n\nexport type MultiStepFormActionsProps = React.ComponentProps<\"div\">;\n\n/** Back and Continue. Continue becomes Back to review after an edit, and the submit label on the last step. */\nexport function MultiStepFormActions({ className, ...rest }: MultiStepFormActionsProps) {\n const { index, steps, back, returnTo, status, labels } = useMultiStepForm();\n const reduce = useReducedMotion();\n const last = index === steps.length - 1;\n const locked = status === \"submitting\" || status === \"done\";\n const label =\n status === \"submitting\" ? labels.submitting : status === \"done\" ? labels.done : last ? labels.submit : returnTo != null ? labels.backToReview : labels.continue;\n const glyph = status === \"submitting\" || status === \"checking\" ? \"spin\" : status === \"done\" ? \"tick\" : null;\n\n return (\n
\n \n {status === \"error\" && (\n \n {labels.error}\n \n )}\n \n
\n \n \n {labels.back}\n \n \n
\n
\n );\n}\n\n// The primary button's width glides between \"Continue\" and the longer submit label,\n// while the label itself slides and the spinner or tick takes its place in front.\nfunction ContinueButton({ label, glyph, busy, done }: { label: string; glyph: \"spin\" | \"tick\" | null; busy: boolean; done: boolean }) {\n const reduce = useReducedMotion();\n const sizer = useRef(null);\n // -1 until measured, so the first paint is simply auto.\n const width = useMotionValue(-1);\n const cssWidth = useTransform(width, (w) => (w < 0 ? \"auto\" : w));\n useLayoutEffect(() => {\n const w = sizer.current?.offsetWidth;\n if (!w) return;\n if (width.get() < 0 || reduce) width.set(w);\n else animate(width, w, spring.snappy);\n }, [label, glyph, width, reduce]);\n\n const content = (\n <>\n {glyph && (\n \n {glyph === \"spin\" ? (\n \n \n \n \n ) : (\n \n \n \n )}\n \n )}\n {label}\n \n );\n\n return (\n <>\n \n \n \n {content}\n \n \n \n {content}\n \n \n \n \n \n {busy ? label : done ? label : \"\"}\n \n \n );\n}\n\nexport type MultiStepFormSummaryItem = { step: string; label: string; value: React.ReactNode };\nexport type MultiStepFormSummaryProps = React.ComponentProps<\"div\"> & {\n items: MultiStepFormSummaryItem[];\n /** Shown for values that are empty. */\n emptyValue?: React.ReactNode;\n};\n\n/** The review: answers grouped by step, each group with an Edit that returns here when done. */\nexport function MultiStepFormSummary({ items, emptyValue = \"Not set\", className, ...rest }: MultiStepFormSummaryProps) {\n const { steps, edit, status } = useMultiStepForm();\n const groups = steps.map((s) => ({ step: s, rows: items.filter((it) => it.step === s.id) })).filter((g) => g.rows.length);\n const locked = status === \"submitting\" || status === \"done\";\n return (\n
\n {groups.map(({ step, rows }) => (\n
\n
\n

{step.label ?? step.title}

\n edit(step.id)}\n aria-label={`Edit ${(step.label ?? step.title).toLowerCase()}`}\n className={cn(\n \"group/edit relative -my-1 -mr-1.5 inline-flex h-6 items-center gap-1 rounded-md px-1.5 text-[12px] text-fg-2 outline-none\",\n \"transition-[background-color,color,scale] duration-150 ease-out hover:bg-hover hover:text-fg active:scale-[0.95] active:duration-75 disabled:opacity-50\",\n \"focus-visible:outline-1 focus-visible:outline-offset-1 focus-visible:outline-fg-3 focus-visible:outline-solid\",\n \"before:absolute before:-inset-2.5 before:content-[''] pointer-fine:before:hidden\",\n )}\n >\n \n Edit\n \n
\n
\n {rows.map((r) => (\n
\n
{r.label}
\n
{r.value === \"\" || r.value == null ? {emptyValue} : r.value}
\n
\n ))}\n
\n
\n ))}\n
\n );\n}\n", "type": "registry:ui" } ], "docs": "https://www.stealth.pm/ui/multi-step-form" }