Multi-step forms
Build a long form as a sequence of steps. Every step stays rendered, and all but the current one are hidden.
On this page
Hiding steps
entry-form.tsxconst subscribe = () => () => {};
const hydrated = useSyncExternalStore(subscribe, () => true, () => false);
Becomes `true` once hydrated
<fieldset hidden={hydrated && step !== 0} ref={stepOne}>
Every step but the current one is `hidden`
{/* step 1 */}
</fieldset>
<fieldset hidden={hydrated && step !== 1}>
{/* step 2 */}
</fieldset>Wrap each step in a <fieldset> and mark every step but the current one hidden. The hidden controls stay in the DOM, so moving between steps loses nothing, and the form is sent once at the end.
Hide steps only once hydrated. Without JavaScript the form is one long page, submitted in a single request.
Per-step validation
entry-form.tsxconst next = () => {
const controls = stepOne.current?.querySelectorAll('input') ?? [];
Only the controls inside the current step
const invalid = [...controls].find((control) => !control.checkValidity());
if (invalid !== undefined) {
invalid.focus();
return;
}
setStep(1);
};“Next” checks only the controls inside the current step with checkValidity(). The later steps are not filled in yet, so checking the whole form would always fail.
useForm shows an error when the person leaves a control. Move focus to the first failed control, and its error appears once they leave it.
The submit button
entry-form.tsx{(!hydrated || step === 1) && <button type="submit">Submit</button>}Once hydrated, render the submit button on the last step only.
Pitfall
Enter in a text field clicks the form’s first submit button, even one inside a hidden step. The whole form would be sent from an earlier step.
Errors after submit
entry-form.tsxconst STEP_OF: Record<string, number> = {
name: 0,
email: 0,
title: 1,
minutes: 1,
};
const [shownState, setShownState] = useState(state);
if (state !== shownState) {
In the render that receives a new `state`, switch to the step holding the error
setShownState(state);
const failed = Object.keys(state.errors ?? {}).map(
(key) => STEP_OF[key] ?? 0,
);
if (failed.length > 0) setStep(Math.min(...failed));
}After a failed submission, useForm moves focus to the first failed control on the page. A control inside a hidden step cannot take focus.
Switch during render to the earliest step with a control in state.errors. The control is visible first, so focus lands on it.
The check on submit covers the hidden steps too. A failure there stops the submission without a visible error.
Two-step demo
One <form> that asks for contact details on the first step and the talk on the second.
Try it
- Press “Next” with the name empty. The form stays on the step and focus moves to the name.
- Fill the first step, move on, and press “Back”. What you typed is still there.
- Type
90as the length on the second step and press “Submit”. The submission stops and the error shows.