Common problems
The bugs most multi-step forms run into, and the fix for each.
Almost every multi-step form bug is one of these. Each maps to a core pattern.
Validation shows errors, but the step still changes
Symptom: the form shows its errors, yet the person ends up on the next step.
Cause: the form library validated the fields, but the move did not go
through the form. A separate Continue button, Stepper.Next or a trigger
called next() or goTo() directly, and the step itself has no schema, so
nothing stopped it.
Fix: put the schema on the step. next() then validates no matter what
called it, and with linear the triggers cannot jump ahead.
const checkout = defineStepper(
[
{ id: "personal", schema: personalSchema },
{ id: "review" },
],
{ linear: true },
);Keep driving the move from the form's submit as well, so the form library shows its field errors. See Pattern 4 and Pattern 9.
Values are not saved
Symptom: the review step is empty, or stepper.data is {}.
Cause: the step moved with stepper.next() and the values were never
handed over. Without an argument, next() only validates what the step
already has stored.
Fix: pass the values in the call.
await stepper.next(values);If the values are passed and still missing, check the result: a guard that
returned false discards them.
const result = await stepper.next(values);
if (!result.accepted) console.log(result.reason);See Pattern 1.
The form is empty after going back
Symptom: Back shows an empty form and the person has to type everything again.
Cause: each step mounts a fresh form, and it was not given the saved values.
Fix: use the step's data as the form's initial values.
const form = useForm({ defaultValues: stepper.data.personal });If what is lost is not form values but component state (an editor, a file picker), see Keeping steps mounted.
The review page shows old values
Symptom: a step was edited, but the review still shows what it had before.
Cause: the review copied the data into its own state once, or the edit never wrote back to the flow.
Fix: read stepper.data while rendering, and save edits with next(values)
or setData.
function ReviewStep() {
const stepper = checkout.useStepperContext();
const { shipping } = stepper.data; // read on every render
return <p>{shipping?.address}</p>;
}The saved draft is not restored
Symptom: the snapshot is in storage, but the flow starts empty.
Cause: snapshot is read once, when the flow is created. If the saved
value arrives later (an effect, a request), the option has already been used.
Fix: apply it with restore when it arrives.
useEffect(() => {
const saved = localStorage.getItem("checkout");
if (saved) stepper.restore(JSON.parse(saved));
}, []);See Saving and resuming.
Async validation runs, but the result is ignored
Symptom: the check passes or fails, yet what happens next does not match.
Cause: the call was not awaited, so the code branched on a promise, which is always truthy.
Fix: await the move and read accepted.
const result = await stepper.next(values);
if (!result.accepted) showErrorBanner();In a guard, the same mistake is computing the answer without returning it:
guard: async ({ data }) => {
const ok = await api.check(data);
return ok; // returning nothing would allow the move
},While the check runs isPending is true. Bind your submit button to it to
show progress; a second next() is refused anyway.
Reading the stepper after an await shows the old step
Symptom: right after await stepper.next(values), stepper.current.id is
still the step that was just left.
Cause: the stepper in your handler is the one from the render that
created the handler. It does not change; the component gets a new one on the
next render.
Fix: use the result of the call.
const result = await stepper.next(values);
if (result.accepted && result.to === "review") scrollToTop();The submit button is enabled too early
Symptom: the final action is available before every step is done, or a check mark shows on a step that was skipped.
Cause: treating "before the current step" as "done". A step that was jumped over or skipped by a branch is not complete.
Fix: ask for the state.
const ready = stepper.steps.every(
(step) => step.id === stepper.current.id || stepper.state(step.id) === "complete",
);In a flow with branches, check only the steps that are part of the path taken. See Step state.
A step lost its check mark after an edit
Symptom: someone goes back and changes a step that was complete. Its check mark disappears, and in a linear flow so do the ones after it; the triggers for those steps are disabled.
Cause: this is intended. A step is complete while its data is what
next() validated. Once setData writes something else, the step has to be
validated again, and a linear flow does not let anyone past it until it is.
The data of the later steps is kept.
Fix: leave the edited step through next(). To return to the review in
one press, keep calling next() until it is reached, as in
Pattern 6.
A form library that only hands its values over on submit (next(values))
never triggers this: the step is validated in the same call that changes it.
The order was submitted twice
Symptom: a double click on the last button sends two requests.
Cause: the request is started from your own click handler, or onFinish
does not return its promise, so the flow finishes before the request does.
Fix: make the request in onFinish and return its promise. The flow is
pending while it runs and finished once it resolves; in both states next()
is refused. See
Pattern 7.
Ready to build it for real? Pick an implementation: React Hook Form, TanStack Form or Conform.
Last updated on