Multi-Step Forms#

Formisch does not currently provide a built-in API for wizard-style multi-step forms. The recommended interim pattern is one useForm instance per step, with each step having its own Valibot schema 1. A first-class useMultiStepForm API is under active design in Discussion #108 2.

Current Guidance#

The official docs point readers directly to the community discussion for wizard patterns 3. The underlying reason is architectural: Formisch validates an entire schema through a single opaque parse function — partial/scoped validation is not supported, so a single form cannot cleanly validate one step at a time 4. Separate useForm instances per step give each step its own scoped validation and submission for free.

Planned useMultiStepForm API#

The proposed API formalizes the multi-form-per-step pattern into a unified abstraction 2:

MultiStepFormStore shape:

interface MultiStepFormStore<TSchemas extends Record<string, Schema>> {
  steps: { [TKey in keyof TSchemas]: FormStore<TSchemas[TKey]> };
  outputs: { [TKey in keyof TSchemas]?: InferOutput<TSchemas[TKey]> };
  current: keyof TSchemas;
}

Key design decisions from the discussion 2:

• One FormStore per step — each step gets its own schema and isolated state.
• Standalone navigation functions — next(), previous(), and goTo() change only .current; they do not validate automatically. This follows Formisch's modular, tree-shakeable API philosophy.
• Explicit output capture — a capture() function must be called manually inside submit handlers before advancing steps. This is necessary because Valibot schemas can transform input during validation, so the raw FormStore input may differ from the validated output.
• Conditional branching — handled by calling goTo() in submit handlers based on user input or server responses.
• Repeatable steps — modeled with v.array() inside a step's schema rather than repeating steps.

Related: Subset Validation (Issue #173)#

Multi-step forms are a primary use case cited in Issue #173, which requests first-class path-scoped validation 5. The maintainer's response there reconfirms the one-form-per-step recommendation and notes that useMultiStepForm is the planned long-term solution 1.

Key References#