Multi-step Forms

Multi-step forms are a way to break down a form into smaller, more manageable steps.

Multi-step forms are easily implemented with Crustack form's flexible architecture.

Each step can be handled independently by using the Form component's onSubmit event handler. By calling event.stopPropagation(), you can prevent the event from reaching the root form and triggering a premature submission.

In-memory steps

Below is an example of a three-step form that allows users to navigate between steps using back and next buttons.

import { defineForm } from '@crustack/form'

type Step = 'step1' | 'step2' | 'step3'
type FormValues = { step: Step }
type FormMeta = Step

const form = defineForm<FormValues, any, any, FormMeta>()

const MultistepForm = () => {
  return (
    <form.Root
      initialValues={{ step: 'step1' }}
      onSubmit={(values, ctx) => {
        // jump to step
        if (ctx.submission.meta) {
          return ctx.setFieldValue('step', ctx.submission.meta)
        }
        // step1 => step2
        if (values.step === 'step1') {
          return ctx.setFieldValue('step', 'step2')
        }
        // step2 => step3
        if (values.step === 'step2') {
          return ctx.setFieldValue('step', 'step3')
        }
        // step3 => submit
        postMyForm(values)
      }}
    >
      {(ctx) => (
        <div>
          {ctx.values.step === 'step1' && (
            <form.Form>
              {/* Use the `tryToSubmit` method to move to a specific step. */}
              <button
                type="button"
                // Jump to step3 with validation of the current values
                onClick={() => ctx.tryToSubmit('step3')}
                children="Skip and jump to Step 3"
              />
              ...
              {/*
                Make use of the native 'submit' button to move to the next step.
                This will try to submit the form, touch & validate the mounted fields.
              */}
              <button children="Move to Step 2" />
            </form.Form>
          )}

          {ctx.values.step === 'step2' && (
            <form.Form>
              <button
                type="button"
                // no need for validation when going back
                onClick={() => ctx.setFieldValue('step', 'step1')}
                children="Back to Step 1"
              />
              ...
              {/* Same as "Move to Step 2" */}
              <button children="Move to Step 3" />
            </form.Form>
          )}

          {ctx.values.step === 'step3' && (
            <form.Form>
              <button
                type="button"
                // no need for validation when going back
                onClick={() => ctx.setFieldValue('step', 'step2')}
                children="Back to Step 2"
              />
              ...
              <button children="Submit the form" />
            </form.Form>
          )}
        </div>
      )}
    </form.Root>
  )
}

Multi-step Forms

In-memory steps

On this page