react-step-form

A headless, unstyled React component library for building animated, stateful multi-step flows. This library handles flow state and transitions — you bring your own UI.

✨ Features

• 🔁 Step-based flow management (forward/back/reset)
• 💾 Pluggable storage adapter system (local/session/custom)
• 🎬 Animated transitions using framer-motion
• ⚛️ Clean React context API
• 🧩 Optional welcome and completion screens
• 🪶 Zero styling or UI constraints — fully unstyled/headless

Demo: https://benjamincharity.github.io/react-step-form/

📦 Installation

npm install @benjc/react-step-form

Required Peer Dependencies

Install these if not already present in your app:

npm install react framer-motion

💡 react-hook-form and zod are used in examples for validation, but are not required.

🚀 Usage

import { StepFlowProvider } from '@benjc/react-step-form';

function MyFlow() {
  return (
    <StepFlowProvider id="my-flow">
      <StepOne />
      <StepTwo />
      <StepThree />
    </StepFlowProvider>
  );
}

Optional: Welcome and Complete Screens

<StepFlowProvider welcomeComponent={WelcomeScreen} completeComponent={CompleteScreen} id="my-flow">
  <StepOne />
  <StepTwo />
</StepFlowProvider>

🧠 API: useStepFlow

Use this hook to control the flow programmatically.

const {
  currentStep,
  currentStepNumber,
  flowStarted,
  isComplete,
  stepData,
  startFlow,
  goNext,
  goBack,
  setStepData,
  restartFlow,
} = useStepFlow();

Function Description

| Function | Description | | --------------- | --------------------------------------------- | | startFlow() | Starts the flow manually | | goNext() | Moves to the next step | | goBack() | Returns to the previous step | | restartFlow() | Clears progress and restarts the flow | | setStepData() | Merges custom data into persistent step state |

💾 Storage Adapter

This library uses a storage adapter abstraction. You can use localStorage, sessionStorage, cookies, or any custom implementation.

Example: How To Create a Session Storage Adapter

export const sessionStorageAdapter = {
  getFlowState: (id) => {
    const raw = sessionStorage.getItem(id);
    return raw ? JSON.parse(raw) : {};
  },
  setCurrentStep: (id, step) => {
    const state = sessionStorageAdapter.getFlowState(id);
    sessionStorage.setItem(id, JSON.stringify({ ...state, currentStep: step }));
  },
  setFlowStarted: (id, started) => {
    const state = sessionStorageAdapter.getFlowState(id);
    sessionStorage.setItem(id, JSON.stringify({ ...state, flowStarted: started }));
  },
  setIsComplete: (id, complete) => {
    const state = sessionStorageAdapter.getFlowState(id);
    sessionStorage.setItem(id, JSON.stringify({ ...state, isComplete: complete }));
  },
  setStepData: (id, data) => {
    const state = sessionStorageAdapter.getFlowState(id);
    sessionStorage.setItem(id, JSON.stringify({ ...state, stepData: data }));
  },
  clear: (id) => sessionStorage.removeItem(id),
};

Then pass in the custom storage adapter to the provider:

<StepFlowProvider id="my-flow" storageAdapter={customStorageAdapter}>
  ...
</StepFlowProvider>

Step Validation Example

You can use your preferred method of validation for each step. Here is an example using react-hook-form and zod.

import { useForm } from 'react-hook-form';
import { z } from 'zod';
import { zodResolver } from '@hookform/resolvers/zod';

const schema = z.object({
  email: z.string().email(),
});

export const EmailStep = () => {
  const { goNext, setStepData, stepData } = useStepFlow();
  const form = useForm({
    resolver: zodResolver(schema),
    defaultValues: { email: stepData.email || '' },
  });

  const onSubmit = (data) => {
    setStepData({ ...stepData, ...data });
    goNext();
  };

  return (
    <form onSubmit={form.handleSubmit(onSubmit)}>
      <input {...form.register('email')} />
      <button type="submit">Next</button>
    </form>
  );
};