React Step Builder

React Step Builder is a headless, unopinionated, multi-step interface builder.

Version 3 introduces some breaking changes. If you are upgrading from earlier versions, please read the documentation carefully.

Global state management methods are removed from the library. React Step Builder will only focus on building step-by-step interfaces starting from version 3. You may use a state management tool of your choice. If this is bad news for you, I am sorry 🙇‍♂️

Installation

Using npm:

npm install react-step-builder

Usage

Example:

import{Steps,StepsProvider,useSteps}from"react-step-builder";constApp=()=>{return(<StepsProvider><MySteps/></StepsProvider>);};constMySteps=()=>{const{ next, prev }=useSteps();return(<Steps><div><h1>Step 1</h1></div><div><h1>Step 2</h1></div><div><h1>Step 3</h1></div></Steps>);};exportdefaultApp;

Documentation

<Steps />

A component whose each direct sibling is treated as a step. Do not add anything else inside Steps component as they will be treated as a separate step.

❌ Incorrect:

<Steps><Step1/><Step2/><NotAStep/></Steps>

✅ Correct:

<Steps><Step1/><Step2><NotAStep/></Step2></Steps>

This reason for this method is due to React's composition over inheritance principle. It also allows you to manage your state easily in the parent component.

Property	Type	Description
onStepChange	(context?: { from: number; to: number }) => void	Runs on every step change. Receives the previous and next step numbers. Does not run on initial render.
beforeNext	() => boolean | Promise<boolean>	A guard function called before moving to the next step. Return false to block navigation. Supports async validation.

---

useSteps

A special hook that accesses the state of <Steps /> component and exposes methods to move between steps.

const stepsState = useSteps();

These are the properties inside stepsState object.

Property	Type	Description
total	number	Total number of steps
current	number	Current step number
progress	number	Progress of the current step, value between 0 and 1
next	() => Promise<boolean>	Move to the next step. Returns true if navigation succeeded, false if blocked by beforeNext.
prev	() => void	Move to the previous step
jump	(step: number) => void	Jump to the given step
reset	() => void	Reset to the first step
isFirst	boolean	If the step is the first
isLast	boolean	If the step is the last
hasPrev	boolean	If the step has any previous step
hasNext	boolean	If the step has any next step

---

<StepsProvider />

The component that renders <Steps /> should be wrapped with StepsProvider component. useSteps can only be called in a component that is rendered in the DOM tree under StepsProvider.

Property	Type	Description
startsFrom	number	The default step number to be rendered.

Step numbers start from 1 and goes up to the count of direct siblings given to the Steps component. If the number is out of range, first step is rendered by default.

---

Step Change Callback

onStepChange runs on every step change and optionally receives a context object with from and to step numbers.

constMySteps=()=>{const{ next, prev }=useSteps();consthandleStepChange=(context)=>{console.log(`Moved from step ${context.from} to step ${context.to}`);};return(<StepsonStepChange={handleStepChange}><div>Step 1</div><div>Step 2</div></Steps>);};

---

Step Validation

Use beforeNext to validate before allowing navigation to the next step. The function can be synchronous or asynchronous.

constMySteps=()=>{const{ next }=useSteps();// Sync validationreturn(<StepsbeforeNext={()=>formIsValid()}><div>Step 1</div><div>Step 2</div></Steps>);};

// Async validation<StepsbeforeNext={async()=>{constisValid=awaitvalidateOnServer();returnisValid;}}>

next() returns a Promise<boolean> indicating whether navigation was allowed:

consthandleNext=async()=>{constmoved=awaitnext();if(!moved){showValidationErrors();}};

---

Reset

Use reset() to return to the first step:

const{ reset }=useSteps();<buttononClick={reset}>Start Over</button>;