Ok. I gave it another thought. We definitely need to store the current step and we need functions to go to the next one, the previous one and a specific step. We also need to find a way to store the output of a completed step. This is because the Valibot schema may transform the input.

The type of the multi step form should probably look like this:

import { Schema, FormStore } from '@formisch/...';

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

And using a multi step form might look like this:

import { getInput, next } from '@formisch/...';

// Create the multi step form
const multipStepForm = useMultiStepForm({
  schemas: { step1: Step1Schema, step2: Step2Schema, ... },
  // other config here...
});

// Access and use a specific step
const input = getInput(multipStepForm.steps.step1);

// Check the current step
if (multipStepForm.current === 'step2') {
  // You can render the step 2 UI here or do other stuff
}

// And moving to the next step (e.g. as part of submitting the previous step) could look like this
next(multipStepForm);

useForm() (for forms) and useMultiStepForm() (for multi step forms) sounds good to me.

We don't necessarily need to implement such properties and navigation functions.
Personally, I can still use the useStepper() composable for navigation or you can implement this logic yourself.

But what would be the goal of useMultiStepForm() then?
Should the step objects stay separate or should they be merged?
Should you be able to validate the current step manually via a validate method or should Formisch manage validation automatically via a validateOnNext property as dosubot mentioned?

In my case I would like to somehow validate each step before navigating to the next step.
But I don't have much experience with multi-step forms.
Are there any other use cases to keep in mind?

(Edit: I just saw the comment above regarding the navigation functions.)

Right now, I think functions like next, previous and goTo should not validate or do anything specific. I think they should just change the .current property. Users should call them inside of the submit handler (e.g. to go to the next step) or when the user clicks the back button to jump back to the previous step.

One thing I am not sure yet is how we capture the output of a step and store it in .outputs. A simple solution would be to provide a function for that (e.g. capture(multipStepForm, { step: 'step1', output: ... })) and users have to call it manually inside of the submit handler before calling next.

Calling next, previous, goTo manually inside the submit handlers sounds good.

Here's my research on how other libraries handle multi-step forms, plus a design proposal for Formisch.

How Others Do It

VueUse useStepper [1] — A pure navigation utility with no form coupling. Accepts steps as an array of names or an object with metadata, and returns current, index, goToNext(), goToPrevious(), goTo(step), isFirst, isLast, etc. Clean and composable, but validation/data-sharing is entirely up to you.

React Hook Form [2] — No built-in wizard API. The typical pattern is a single useForm at the top level, useFormContext inside step components, conditional rendering per step, and trigger(fieldNames) to validate only the current step's fields before advancing.

React Final Form [3] — Provides a dedicated "Wizard Form" example: a single form state spans all pages, each page component defines its own field-level or record-level validators, and navigation is manual but well-documented.

TanStack Form / Formik — No built-in multi-step support. Developers roll their own step state on top of standard form APIs.

Key takeaway: No existing library offers a schema-first wizard primitive. Most separate step navigation from form state and rely on developers to glue them together.

Formisch's Architectural Constraint

Currently, validate() always validates the entire schema — there's no path-scoped or partial-schema validation [4] [5]. This is the main blocker for native multi-step support and why the current workaround is separate useForm instances per step.

Proposed API Design for Formisch

Building on your initial sketch and taking inspiration from VueUse's ergonomics, here's a proposal that stays true to Formisch's schema-first philosophy:

import * as v from 'valibot';
import { useMultiStepForm, getInput } from '@formisch/react'; // or vue, solid, etc.

// Each step is its own Valibot schema — single source of truth
const Step1Schema = v.object({ name: v.pipe(v.string(), v.minLength(1)) });
const Step2Schema = v.object({ email: v.pipe(v.string(), v.email()) });
const Step3Schema = v.object({ plan: v.picklist(['free', 'pro']) });

const form = useMultiStepForm({
  steps: {
    personal: { schema: Step1Schema },
    contact:  { schema: Step2Schema },
    billing:  { schema: Step3Schema },
  },
  onSubmit: (data) => {
    // `data` is fully typed as Step1 & Step2 & Step3
  },
});

Navigation & State

form.current;       // 'personal' | 'contact' | 'billing'
form.index;         // 0, 1, 2
form.isFirst;       // boolean
form.isLast;        // boolean

form.goToNext();    // validates current step, advances if valid
form.goToPrevious();// no validation needed going back
form.goTo('billing'); // jump (optionally validates intervening steps)

Per-Step Access

// Access a specific step's form store (typed to its schema)
const nameInput = getInput(form.steps.personal);

// Or use the current step dynamically
form.steps[form.current]; // FormStore for the active step

Validation Strategy

const form = useMultiStepForm({
  steps: { ... },
  // When to validate before advancing
  validateOnNext: true, // default: validate current step on goToNext()
  // Or finer control:
  // validateOnNext: 'current' | 'all-visited' | false
});

Under the hood, each step gets its own FormStore (like separate useForm calls today), but useMultiStepForm orchestrates them as a unified wizard with merged output types.

Why This Design Works for Formisch

1. Schema-first — Each step's structure, validation, and types come from its Valibot schema. No separate type annotations needed.
2. Sidesteps the partial-validation blocker — Each step is its own schema/store, so validation is naturally scoped without needing path-level validate().
3. Fully typed — form.steps.personal knows its fields; onSubmit receives the intersection of all step schemas; navigation methods are type-safe.
4. Framework-agnostic — The same API shape works across React, Vue, Solid, Svelte via Formisch's existing build-time primitive swapping.
5. Composable — Power users can still use separate useForm instances if they need custom orchestration.

Optional Extensions (future)

• form.completedSteps — Set of steps that passed validation
• form.canGoTo(step) — Whether a step is reachable (e.g., require sequential completion)
• FieldArray-like step arrays for dynamic wizard flows
• Cross-step validation via a top-level schema that runs on final submit

Let me know if you'd like me to dig deeper into any specific aspect — e.g., how the merged type inference would work with Valibot's IntersectSchema, or how goTo should behave when skipping steps.

To reply, just mention @dosu.

Share context across your team and agents. Try Dosu.

@dosu Formisch would never do form.goToNext() because a modular design is important to us!

You're absolutely right — thanks for the correction! Formisch's modular design means actions are standalone functions like next(multiStepForm), not methods on the store. That's consistent with how getInput(form), setInput(form, ...), validate(form), etc. already work [1]. My mistake for suggesting stepForm.next() / stepForm.previous() / stepForm.goTo(...) — those should be:

import { next, previous, goTo } from '@formisch/...';

next(multiStepForm);
previous(multiStepForm);
goTo(multiStepForm, 'step2');

This keeps each navigation action tree-shakeable and follows the existing pattern. Your proposed MultiStepFormStore type with separate steps, output, and current properties looks clean — especially storing the transformed output per completed step separately from the live FormStore input. That handles the Valibot transformation case well.

To reply, just mention @dosu.

Docs are dead. Just use Dosu.