@k8ordo/form

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.tsx
const 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.tsx
const 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.

Warning

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.tsx
const 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.

Playground

Two-step demo

One <form> that asks for contact details on the first step and the talk on the second.

Step 1 of 2

Contact
The talk

Try it

  1. Press “Next” with the name empty. The form stays on the step and focus moves to the name.
  2. Fill the first step, move on, and press “Back”. What you typed is still there.
  3. Type 90 as the length on the second step and press “Submit”. The submission stops and the error shows.
k8ordo

React libraries that use Baseline features without holding back.