rhf-stepper — headless multi-step form management for react-hook-form

[omerrkosar]

I built a lightweight wrapper that adds step management and per-step validation to react-hook-form. The main problem it solves: you shouldn't have to manually track which fields belong to which step or call trigger() with field name arrays.

What it does

• Auto field-to-step tracking — wrap fields in <Step>, and next() only validates the current step's fields
• Per-step validation — works with zodResolver, yupResolver, or inline rules
• onLeave callback — run async operations (API calls) between steps, only fires on next(), not on re-renders
• Headless — no built-in UI, works with MUI, Shadcn, Ant Design, or plain HTML
• React Native support — pure context + hooks, no DOM dependency
• useStepper() hook — access activeStep, next, prev, isFirstStep, isLastStep from any child component

Quick example

import { useForm, FormProvider } from 'react-hook-form'
import { Stepper, Step, Controller, useStepper } from 'rhf-stepper'

function MultiStepForm() {
  const form = useForm()

  return (
    <FormProvider {...form}>
      <form onSubmit={form.handleSubmit((data) => console.log(data))}>
        <Stepper>
          {({ activeStep }) => (
            <>
              <Step>
                {activeStep === 0 && (
                  <Controller name="name" rules={{ required: 'Required' }}
                    render={({ field }) => <input {...field} />} />
                )}
              </Step>
              <Step>
                {activeStep === 1 && (
                  <Controller name="address" rules={{ required: 'Required' }}
                    render={({ field }) => <input {...field} />} />
                )}
              </Step>
              <Navigation />
            </>
          )}
        </Stepper>
      </form>
    </FormProvider>
  )
}

function Navigation() {
  const { next, prev, isFirstStep, isLastStep } = useStepper()
  return (
    <div>
      {!isFirstStep && <button type="button" onClick={prev}>Back</button>}
      {isLastStep
        ? <button key="submit" type="submit">Submit</button>
        : <button key="next" type="button" onClick={next}>Next</button>}
    </div>
  )
}

Links

• npm
• GitHub
• Docs

Would love feedback from the community!