KQ-1327 · SETUP/WIZARD

Setup Wizard

A multi-step setup flow whose rail is also its record: the fill follows the step on glide, and a valid Next lifts the step's answer off the panel and flies it to that step's place on the rail, x on glide and y on snap so the path bows, where it stays. A Next the step cannot take leans the rail toward the next node on flick and pulls it back on snap while each field says why; panels swap by direction by 16px on snap inside a box that glides to the measured height, and the review lists every answer with an Edit link that returns straight to it. The rail is a list of buttons, the panel a real form where Enter is Next, choices are native radio groups moved with the arrow keys, and the new panel's heading takes focus as it arrives.

KQ-1327 · SETUP/WIZARD

Set up Fieldline

Four steps. What you answer stays on the rail.

step 1 of 4 · workspace

Open it on the Studio stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/setup-wizard

Props

steps: WizardStep[]; default defaultWizardSteps; The steps before the review: id, title, description, fields (text, email, url, choice, segmented or toggle with their rules) and an optional summary for the rail.
value / defaultValue: WizardValues; default — / defaultWizardValues; Every answer, by field id.
onValueChange: (values: WizardValues) => void; default —; Fires from the keystroke, pick or switch that changed an answer, with every answer.
step / defaultStep: number; default — / 0; The step on screen; steps.length is the review. Controlled, the wizard asks through onStepChange and waits.
onStepChange: (index: number) => void; default —; Fires from Next, Back, Edit or a rail node with the step asked for.
onInvalid: (step: number, fieldIds: string[]) => void; default —; A Next or a rail jump was held, with the fields that need attention.
onSubmit: (values: WizardValues) => void | Promise<void>; default —; Runs from the review's button. A promise holds it pending; a rejection's message is shown in an alert.
onRestart: () => void; default —; Start over was pressed on the finished state.
rail: "side" | "top" | "bar"; default "side"; Beside the panel with each answer kept under its step, across the top with answers under the labels, or a slim segmented bar.
validate: "next" | "blur" | "live"; default "next"; When a field's message shows: after a held Next, when the field is left, or as you type (with a tick on valid fields).
direction: "horizontal" | "vertical" | "depth"; default "horizontal"; The axis panels travel on between steps.
title: string; default "Set up your workspace"; The heading and accessible name.
subtitle: string; default —; A line under the heading.
reviewTitle: string; default "Review"; The review step's heading and rail label.
submitLabel: string; default "Create workspace"; The review's button.
pendingLabel: string; default "Working…"; The button while onSubmit is pending; the button keeps its width.
doneTitle: string | ((values: WizardValues) => string); default "<name> is ready"; The finished state's heading.
doneBody: string; default —; The finished state's line.
status: "ready" | "loading" | "error"; default "ready"; Loading draws placeholder rows; error offers Retry.
onRetry: () => void; default —; The Retry button of the error state.
label: string; default —; The region's accessible name when it should differ from the title.
sound: boolean; default false; A swish on each step change and clicks on choices, Edit and a held Next.
disabled: boolean; default false; Shows the wizard but takes no input.
className: string; default —; Classes for the region; give it a max height and it scrolls inside itself.

Prop	Type	Default	Description
steps	WizardStep[]	defaultWizardSteps	The steps before the review: id, title, description, fields (text, email, url, choice, segmented or toggle with their rules) and an optional summary for the rail.
value / defaultValue	WizardValues	— / defaultWizardValues	Every answer, by field id.
onValueChange	(values: WizardValues) => void	—	Fires from the keystroke, pick or switch that changed an answer, with every answer.
step / defaultStep	number	— / 0	The step on screen; steps.length is the review. Controlled, the wizard asks through onStepChange and waits.
onStepChange	(index: number) => void	—	Fires from Next, Back, Edit or a rail node with the step asked for.
onInvalid	(step: number, fieldIds: string[]) => void	—	A Next or a rail jump was held, with the fields that need attention.
onSubmit	(values: WizardValues) => void \| Promise<void>	—	Runs from the review's button. A promise holds it pending; a rejection's message is shown in an alert.
onRestart	() => void	—	Start over was pressed on the finished state.
rail	"side" \| "top" \| "bar"	"side"	Beside the panel with each answer kept under its step, across the top with answers under the labels, or a slim segmented bar.
validate	"next" \| "blur" \| "live"	"next"	When a field's message shows: after a held Next, when the field is left, or as you type (with a tick on valid fields).
direction	"horizontal" \| "vertical" \| "depth"	"horizontal"	The axis panels travel on between steps.
title	string	"Set up your workspace"	The heading and accessible name.
subtitle	string	—	A line under the heading.
reviewTitle	string	"Review"	The review step's heading and rail label.
submitLabel	string	"Create workspace"	The review's button.
pendingLabel	string	"Working…"	The button while onSubmit is pending; the button keeps its width.
doneTitle	string \| ((values: WizardValues) => string)	"<name> is ready"	The finished state's heading.
doneBody	string	—	The finished state's line.
status	"ready" \| "loading" \| "error"	"ready"	Loading draws placeholder rows; error offers Retry.
onRetry	() => void	—	The Retry button of the error state.
label	string	—	The region's accessible name when it should differ from the title.
sound	boolean	false	A swish on each step change and clicks on choices, Edit and a held Next.
disabled	boolean	false	Shows the wizard but takes no input.
className	string	—	Classes for the region; give it a max height and it scrolls inside itself.

Setup Wizard

Set up Fieldline

Workspace

Install

Props