React Hook Form Multi-Step

Create react-hook-forms with multistep functionality.

• ✅ Bring your existing forms using react-hook-form.
• 🚶 Use the stepper component to visualise form progress (or bring your own).
• 💾 Save the state of your form as the user progresses.
• ⛔️ Provides feedback when the form is in an invalid state, blocking progress.
• 📃 Unstyled. As this is just a wrapper around your own forms.

Getting Started

Install react-hook-form-multistep

npm install react-hook-form-multistep

Check out the /examples for simple and complex (custom stepper, controlled components) usage. As a quick primer, here is a very simple example where each form takes in 1 piece of the state, updates it and writes it back to the state variable, provided the data in the form is valid.

1import { useForm } from 'react-hook-form'
2import { useEffect, useState } from 'react'
3import MultiStepForm from 'react-hook-form-multistep'
4
5function App() {
6  const [state, setState] = useState<FormOneData & FormTwoData>({
7    name: 'joe',
8    age: '18',
9  })
10
11  return (
12    <MultiStepForm>
13      <MultiStepForm.Step
14        renderStepForm={({ handleStepSubmit, reportStepValidity }) => (
15          <FormOne
16            data={state}
17            onSubmit={handleStepSubmit((data) => setState({ ...data, ...state }))} // handleStepSubmit(data: FormOneData) => void)
18            reportStepValidity={reportStepValidity} // (isFormStepValid: boolean) => void
19          />
20        )}
21      />
22      <MultiStepForm.Step
23        renderStepForm={({ handleStepSubmit, reportStepValidity }) => (
24          <FormTwo
25            data={state}
26            onSubmit={handleStepSubmit((data) => setState({ ...data, ...state }))}
27            reportStepValidity={reportStepValidity}
28          />
29        )}
30      />
31    </MultiStepForm>
32  )
33}
34
35// FormOne and FormTwo are simple react-hook-forms

Complex forms

For complex forms with deeply nested fields, and particularly ones with useFieldArray the simple setState({ ...data, ...state }) approach to saving each form step will not work. setState does a shallow merge of object properties. The snippet below is a helper which will deeply merge object properties and handles array inputs properly (i.e. overwriting the existing array with the new array in the submitted form step).

1// utility function
2import mergeWith from 'lodash.mergewith'
3import { type DeepPartial } from 'react-hook-form'
4
5export default function mergeFormState<T extends object>(object: T, source: DeepPartial<T>): T {
6  return mergeWith({}, object, source, replaceArrayOnMerge)
7}
8
9const replaceArrayOnMerge = <T,>(objValue: T, srcValue: DeepPartial<T>) => {
10  if (Array.isArray(objValue)) {
11    return srcValue
12  }
13}
14
15// useage
16...
17<FormOne
18    data={store}
19    onSubmit={handleStepSubmit((data) => setState((prevStore) => mergeFormState(prevStore, data)))}
20    reportStepValidity={reportStepValidity}
21/>
22...