React Formik Step Wizard


React multistep wizard library with Formik integration.

This library let's you build multistep form wizards using Formik. How this works is that steps are internally wrapped inside instance, allowing you to configure validation, validation strategy and initial values for each step and make use of Formik's helpful hooks and components like useFormikContext, , and such in your step components. Form submission is handled by the wizard automatically but that is customizable to some extent as well.

Library basically consists of Wizard component that requires a list of step configuration objects. Wizard itself collects inputted form values from each step. Collected values can be accessed using useWizard hook.

Demo

https://kennyhei.github.io/react-formik-step-wizard/

Small demo showcasing the wizard and various use cases such as:

- Step with basic form validation
- Step with form where validation is dependent on what user inputted in previous view
- Skippable step
- Async step
- Final step with summary of inputted data
- Shared footer with navigation buttons
- Shared header with progress bar
- Animated steps
- URL hashes

You can find more information on usage below.

Table of Contents

- Installation
- Quickstart
- How it works
- 1. Configuring list of steps
- 2. Writing your step component(s)
- 3. Setting up the Wizard
- 4. Full example
- What if I don't want to use Formik in step component?
- Navigation
- BasicFooter
- API
- Step object
- Wizard
- useWizard
- Advanced topics
- Skipping steps
- Validating form field based on what user inputted in previous step(s)
- Saving form values in sessionStorage
- Using URL hashes in the wizard
- Animations
- Caveats
- Creating wrapper for steps
- Creating header for wizard
- Creating custom submit handler for step

Installation

NPM:
``
npm install react-formik-step-wizard --save
`

Yarn:
`
yarn add react-formik-step-wizard formik
`

Note: It is also recommended to install yup for validation (it is used in examples below). You can install yup with npm install yup --save or yarn add yup. However, it's not mandatory as you can write your validation function to steps with plain JS as well (see validate).

Quickstart

`js
import React from 'react'
import ReactDOM from 'react-dom/client'
import { Wizard, useWizard, BasicFooter } from 'react-formik-step-wizard'
import { Field, ErrorMessage } from 'formik'
import * as Yup from 'yup'

function StepName() {
return (


ReactDOM.createRoot(document.getElementById('root')).render(

)
`

How it works

You can follow this tutorial step by step. Full code is shown in the end.

$3

Wizard component requires a list of steps. Here's a basic example what the list looks like:

`js
const steps = [
{
id: 'StepName',
component: ,
initialValues: { name: '' },
validationSchema: Yup.object({ name: Yup.string().required('Name is required') })
},
{
id: 'StepAge',
component: ,
initialValues: { age: '' },
validationSchema: Yup.object({ age: Yup.number().positive().required('Age is required') })
},
{
id: 'StepFinal',
component:
}
]
`

Each step object defines component that is used to render the step. Wizard wraps the currently active step inside

- initialValues: Initial values of the Formik fields that are rendered in the component.
- validationSchema / validate: Either define Yup schema or function that validates the form fields.
- validateOnChange: Tells Formik to validate the form on each input's onChange event. Defaults to true.
- validateOnBlur: Tells Formik to validate the form on each input's onBlur event. Defaults to true.

Usually you would need to define at least initialValues and validationSchema / validate (presuming that your step component contains form fields).

You can view the full list of step options here.

$3

If you plan to have form fields in your step component, you should use Formik's Field component to render fields and ErrorMessage to render error messages. For instance, this is what StepName and StepAge could look like:

`js
import { Field, ErrorMessage } from 'formik'
import { useWizard } from 'react-formik-step-wizard'

function StepName() {
return (


Note that we retrieve goToPreviousStep utility function from useWizard hook. You can read more about it here.

$3

Now you can pass the list to Wizard:

`js
steps={steps}
onStepChanged={(fromStep, toStep, wizardValues) => {
console.log('step changed', fromStep.id, toStep.id, wizardValues)
}}
onCompleted={values => console.log('wizard completed', values)}
/>
`

- onStepChanged is called each time step is changed. fromStep and toStep represent step objects. wizardValues is a collection of all inputted values in previously completed steps.
- onCompleted is called when user completes the wizard (i.e. submits last step). values contains the field-value pairs from all steps.

If we look at Quickstart example, then onStepChanged would print this after user has completed first step:

`js
> step changed, StepName, StepAge, { StepName: { firstName: 'John', lastName: 'Doe' } }
`

After second step:

`js
> step changed, StepAge, StepFinal, { StepName: { firstName: 'John', lastName: 'Doe' }, { StepAge: { age: 30 } } }
`

After user has completed the wizard, onCompleted would print this:

`js
> wizard completed, { firstName: 'John', lastName: 'Doe', age: 30 }
`

$3

Here's what the finished code looks like:

`js
import React from 'react'
import { useWizard, Wizard } from 'react-formik-step-wizard'
import { Field, ErrorMessage } from 'formik'
import * as Yup from 'yup'

function StepName() {
return (


return (
steps={steps}
onStepChanged={(fromStep, toStep, wizardValues) => {
console.log('step changed', fromStep.id, toStep.id, wizardValues)
}}
onCompleted={values => console.log('wizard completed', values)}
/>
)
}
`

$3

Then you can omit initialValues and validationSchema / validate attributes from the step object and not just use Formik's Field and ErrorMessage in your step component. You can basically write anything in your component as long as it has a button of type submit for proceeding to the next step or alternatively you can use shared navigation component which will be explained next.

Navigation

If you wish to include a shared navigation for all steps in your wizard, you can create your own component and pass it to Wizard using footer or header props. When you do that, the following properties would be useful to retrieve from Wizard using useWizard hook:

- goToPreviousStep: Function that goes to previous step.
- isFirstStep: Boolean indicating whether step is first step.
- isLastStep: Boolean indicating whether step is last step.
- isLoading: Boolean indicating whether step is in loading state.
- activeStep:
- hidePrevious: Boolean indicating whether "Previous" button should be hidden.
- disablePrevious: Boolean indicating whether "Previous" button should be disabled.
- hideNext: Boolean indicating whether "Next" button should be hidden.
- disableNext: Boolean indicating whether "Next" button should be disabled.
- disableNextOnErrors: Boolean indicating whether "Next" button should be disabled if form has errors.

Here's an example of simple navigation component:

`js
import React from 'react'
import { Wizard, useWizard } from 'react-formik-step-wizard'

const steps = [
{ id: 'Step1', component:

Step 1

function App() {
return (
} />
)
}
`

$3

If you don't wish to create your own navigation component, a basic footer with navigation buttons is included in react-formik-step-wizard. Here's how you can use it:

`js

import React from 'react'
import { Wizard, BasicFooter } from 'react-formik-step-wizard'

const steps = [
{ id: 'Step1', component:

Step 1

function App() {
return (
steps={steps}
footer={}
/>
)
}
`

Note that BasicNavigation has two additional props textNext and textPrevious for customizing button texts. By default they are "Next" and "Previous".

You can customize looks of the basic footer by defining CSS for classes .navigation and .navigation-wrapper.

API

$3

List of step objects that are passed to Wizard have various options you can set. Here's the full specification:

| Name | Type | Default | Description |
|------------------------|------------------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| id | string | | _(Required)_ Unique ID for step component. Form values inputted by user are stored in the Wizard's values object under step ID key. E.g. { [id]: { [field]: [value] } }. Values can be retrieved from Wizard using useWizard hook. |
| component | ReactElement | | Component used for rendering step content. Usually this is always required unless you implement default component object like in the demo/ code. |
| initialValues | object | {} | Contains key-value pairs for step's form fields.

Example:
initialValues: { name: '', email: '' } |
| submitOnChange | boolean | false | Submits form on field change. Useful when user e.g. has to pick a choice from radio buttons. |
| hideNext | boolean | false | Indicates whether to hide submit button. |
| hidePrevious | boolean | false | Indicates whether to hide "Previous" button. |
| disableNext | boolean | false | Indicates whether to disable submit button. |
| disableNextOnErrors | boolean | false | Indicates whether to disable submit button when form has errors. |
| disablePrevious | boolean | false | Indicates whether to disable "Previous" button. |
| keepValuesOnPrevious | boolean | true | Remembers inputted values in current step if user decides to navigate back to previous step without submitting the form. |
| shouldSkip | async (allValues, direction) => stepValues | | Function that returns boolean telling whether the step should be skipped or not.

Params:
- allValues: all form field values from previous steps
- direction: Tells whether user came to the current step by pressing "Previous" (-1) or by pressing "Next" (1) |
| onSubmit | async (stepValues, allValues, actions) => stepValues | | Function that serves as a custom submit handler where you can do things after successful form submission. You should return stepValues.

Params:
- stepValues: form field values filled in current step
- allValues: all form field values from previous steps
- actions: Includes Formik helper functions |
| validate | (stepValues, allValues) => object | | Validate the form's values with a function. If there are errors, return object containing field's name as key and error message as value.

Params:
- stepValues: form field values filled in current step
- allValues: all form field values from previous steps |
| validationSchema | Yup.object | | A Yup schema. This is used for validation. Errors are mapped by key to the inner component's errors. Its keys should match of those values. Example here: https://formik.org/docs/guides/validation#validationschema |
| validateOnBlur | boolean | true | Use this option to tell Formik to run validations on blur events. |
| validateOnChange | boolean | true | Use this option to tell Formik to run validations on change events. |

$3

Wizard controls the step flow. Only required props is steps which contains a list of step config objects. You can customize the wizard by passing custom components using header, wrapper and footer props.

| Name | Type | Description |
|-----------------|------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| steps | list | _(Required)_ List of step objects. See example and configuration instructions above. |
| onStepChanged | (fromStep, toStep, wizardValues) => void | Function that is called when user either submits currently active step or navigates back to previous step. |
| onCompleted | (values) => void | Function that is called when user completes the wizard. |
| header | ReactElement | Header that is shown above the active step. |
| wrapper | ReactElement | Wrapper component that is wrapped around step.component. Useful if you need e.g. styling that is shared across all step components. |
| footer | ReactElement | Footer that is shown below the active step. |
| enableHash | boolean | Enables URL hashes per step. Hash matches with slugified step id (e.g. StepName -> #step-name) and is updated accordingly every time when step is changed. |

$3

Wizard hook that you can use in any step component or in custom header, wrapper and footer component. Used to retrieve info and utility functions related to wizard.

| Name | Type | Description |
|-------------------|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| values | object | Contains all form field values from previously completed steps. Example:

{ StepName: { firstName: 'John', lastName: 'Doe' }, StepAge: { age: 30 } |
| activeStep | object | Active step object. |
| stepNumber | number | Order number of currently active step. Indexing starts from 1. |
| totalSteps | number | Number of total steps. |
| isLoading | boolean | Is step in loading state or not. Set to true when step.onSubmit handler is called and back to false when executing handler is done. |
| isFirstStep | boolean | Is the currently active step the first step. |
| isLastStep | boolean | Is the currently active step the last step. |
| updateStep | (key: string, value: any) => void | Function used to set the step object's [key] attribute to value. Mostly used to manually hide or disable navigational buttons (e.g. hideNext / disableNext). |
| setIsLoading | (truthy: boolean) => void | Function used to set the value of isLoading attribute. |
| goToPreviousStep | () => void | Go to previous step. |
| goToStep | (index: number) => void | Go to step at the specified index. |

Advanced topics

For more advanced use of the wizard I recommend playing with demo and reading code in demo/ folder. Some topics are covered below:

$3

You can define a shouldSkip function that returns boolean value in the step object. If true, step is skipped and wizard moves on the next step (or previous step, depending on if user pressed "Previous" button or "Next" button).

shouldSkip receives two parameters:
- values: All values that were inputted in previous steps
- direction: Either -1 or 1, indicating whether we are moving backwards or forwards in the wizard.

Example:
`js
import { Field, ErrorMessage } from 'formik'
import { Wizard, useWizard } from 'react-formik-step-wizard'

function NonSkippableStep() {
return (


function App() {
return (

)
}
`

$3

Sometimes there's a need to validate field based on what user inputted in previous steps. In this case, you can define a validate function to the step object.

validate receives following parameters:
- stepValues: form field values filled in current step
- allValues: all form field values from previous steps

If there are errors, return object containing field's name as key and error message as value.

Example:
`js
function StepName() {
return (


const steps = [
{
id: 'StepName',
component: ,
initialValues: {
name: ''
}
},
{
id: 'StepFullName',
component: ,
initialValues: {
fullName: ''
},
validate: (stepValues, allValues) => {
const errors = {}
if (!stepValues.fullName.includes(allValues.StepName.name)) {
errors.fullName = 'Full name is missing your first name.'
}
return errors
}
}
]
`

$3

If you want form fields to persist e.g. between page refreshes, you can use sessionStorage to your advantage. react-formik-step-wizard doesn't offer solution out of the box but here's one way you can implement the logic:

`js
function getStepInitialValues(stepId) {
const values = JSON.parse(sessionStorage.getItem('wizardValues'))
return values?.[stepId]
}

const steps = [{
id: 'StepName',
component: ,
initialValues: getStepInitialValues('StepName') || {
name: ''
}
}]

return (
steps={steps}
onStepChanged={(fromStep, toStep, wizardValues) => {
sessionStorage.setItem('wizardValues', JSON.stringify(wizardValues))
}}
/>
)
`

$3

When initiating Wizard, you can enable URL hashes with prop enableHash:

`js
enableHash
steps={[
{ id: 'StepName', component:

Step IDs are converted into URL-friendly hashes. When user is in the first step, URL will be updated with hash /#step-name and when user proceeds to the next step, URL is updated with hash /#step-age. When refreshing page, active step will be chosen based on URL hash. If there is no hash or hash doesn't match with any step, first step is shown.

$3

Check demo/components/WizardStepWrapper.jsx on how to use framer-motion in your steps.

#### Caveats

If you use animation library in your custom wrapper component, then during step change Formik logs warning "A component is changing a controlled input to be uncontrolled." to console. Tested with react-spring and framer-motion.

Since steps are internally using shared Formik instance, I think the issue is that when step is changed, then Formik's initialValues is also updated according to what has been configured in new step object. However, during transition the old step is still rendered couple of times. If old step component is using Formik , internally it's retrieving initialValues which now has the new values from new step, causing said warning as it cannot find anymore corresponding initial value for . This results in component being changed from controlled input to uncontrolled.

Simplified example:

`js
const steps = [
{ id: 'Step1', component: , initialValues: { name: '' }},
{ id: 'Step2', component: , initialValues: { age: '' }}
]

function Wrapper() {
const { activeStep } = useWizard()
return (

key={activeStep.id}
initial={{ opacity: 0 }}
animate={{ opacity: 1}}
exit={{ opacity: 0 }}
transition={{ duration: 0.5}}
>
{activeStep.component}


)
}

return (
} />
)
`

1. First step is rendered, internal Formik instance now has initialValues that equals to { name: '' }
2. User clicks next:
- Active step is changed to Step2
- Internally Wizard provides Formik instance with new initialValues that equals to { age: '' }
3. Transition begins, Step1 is still being rendered and cannot find corresponding initial value, causing Field to change from controlled input to uncontrolled.
4. After transition is done, Step1 is not rendered anymore and everything is OK again.

To my understanding, in this case the warning message is annoying but harmless. It doesn't seem to break anything nor is it visible to end user otherwise in any way. Also when NODE_ENV is set to production, warning message is not logged at all so it will be omitted from your build.

One solution would be to combine all initialValues from step objects to a single one that is then passed to Formik. E.g. for every step in aforementioned example Formik would always be given initialValues that equals to { name: '', age: '' }. However, this basically prevents from using same field names in multiple step objects. Other solution would be to prefix every initial value but that's clumsy as well.

$3

You can wrap steps by defining your own wrapper component. Here's an example:

`js
import { useWizard, Wizard } from 'react-formik-step-wizard'

function StepWrapper() {
const { activeStep } = useWizard()
return (


function App() {
return (
steps={steps}
wrapper={}
/>
)
}
`

$3

You can create header for wizard by defining your own header component. Here's an example:

`js
import { useWizard, Wizard } from 'react-formik-step-wizard'

function Header() {
const { activeStep } = useWizard()
return (