react-multistep-forms

Flexible and customizable multistep form context for React with native React Hook Form integration.

⚠️ Disclaimer: This package is currently under active development.

react-multistep-forms is not yet a stable release and may contain bugs, incomplete features, or security vulnerabilities.

Any developer or end user who downloads or uses this package acknowledges that the package author is not responsible for any data loss, system failure, security issues, or other problems that may arise from its use.

By downloading or using this package, the developer or end user agrees that the author of this package is not liable for any direct, indirect, incidental, or consequential damages arising from its use. Use at your own risk.

It is strongly recommended to thoroughly test the package before using it in any production environment.

For bug reports or suggestions, please open an issue on GitHub Issues."

Installation

Install the package using npm:

1npm install react-multistep-forms

Or using yarn:

1yarn add react-multistep-forms

Basic Usage

Here's a simple example of how to use the multi-step form:

1import React from 'react';
2import { FormProvider, useForm } from 'react-hook-form';
3import {
4  MultistepForm,
5  MultistepFormProvider,
6  StepContainer,
7  Step,
8  ProgressBar,
9  StepControls,
10  NextButton,
11  PrevButton,
12  SubmitButton
13} from 'react-multistep-forms';
14
15function MyForm() {
16  const methods = useForm();
17  
18  const handleSubmit = (data) => {
19    console.log('Form submitted:', data);
20  };
21  
22  // Define which fields belong to which step
23  const stepFieldsMap = {
24    personalInfo: ['firstName', 'lastName'],
25    contactInfo: ['email', 'phone'],
26    addressInfo: ['address', 'city', 'zipCode']
27  };
28  
29  return (
30    <FormProvider {...methods}>
31      <MultistepFormProvider 
32        stepFieldsMap={stepFieldsMap} 
33        onSubmit={handleSubmit}
34      >
35        <MultistepForm className="max-w-md mx-auto p-6 bg-white rounded shadow">
36          <ProgressBar type="dot" className="mb-6" />
37          
38          <StepContainer>
39            <Step title="Personal Information">
40              <div className="space-y-4">
41                <div>
42                  <label>First Name</label>
43                  <input {...methods.register('firstName', { required: true })} />
44                  {methods.formState.errors.firstName && <span>This field is required</span>}
45                </div>
46                <div>
47                  <label>Last Name</label>
48                  <input {...methods.register('lastName', { required: true })} />
49                  {methods.formState.errors.lastName && <span>This field is required</span>}
50                </div>
51              </div>
52            </Step>
53            
54            <Step title="Contact Information">
55              <div className="space-y-4">
56                <div>
57                  <label>Email</label>
58                  <input {...methods.register('email', { required: true, pattern: /^\S+@\S+$/i })} />
59                  {methods.formState.errors.email && <span>Valid email is required</span>}
60                </div>
61                <div>
62                  <label>Phone</label>
63                  <input {...methods.register('phone')} />
64                </div>
65              </div>
66            </Step>
67            
68            <Step title="Address Information">
69              <div className="space-y-4">
70                <div>
71                  <label>Address</label>
72                  <input {...methods.register('address', { required: true })} />
73                  {methods.formState.errors.address && <span>This field is required</span>}
74                </div>
75                <div>
76                  <label>City</label>
77                  <input {...methods.register('city', { required: true })} />
78                  {methods.formState.errors.city && <span>This field is required</span>}
79                </div>
80                <div>
81                  <label>Zip Code</label>
82                  <input {...methods.register('zipCode', { required: true })} />
83                  {methods.formState.errors.zipCode && <span>This field is required</span>}
84                </div>
85              </div>
86            </Step>
87          </StepContainer>
88          
89          <StepControls className="flex justify-between mt-6">
90            <PrevButton>Previous</PrevButton>
91            <NextButton>Next</NextButton>
92            <SubmitButton>Submit</SubmitButton>
93          </StepControls>
94        </MultistepForm>
95      </MultistepFormProvider>
96    </FormProvider>
97  );
98}

Components API

MultistepFormProvider

The context provider for the multi-step form.

Prop	Type	Description
stepFieldsMap	Record<string, string[]>	Maps step keys to field names for validation
onSubmit	() => void	Function called when the form is submitted
children	ReactNode	Child components

MultistepForm

The main container for the multi-step form.

Prop	Type	Description
children	ReactNode	Child components
className	string	CSS class for styling

Step

Represents an individual step in the form.

Prop	Type	Description
title	string	Title of the step
isValid	boolean	Whether the step is valid
children	ReactNode	Content of the step
className	string	CSS class for styling
hideTitle	boolean	Whether to hide the title

StepContainer

Container that manages which step is currently visible.

Prop	Type	Description
children	ReactNode	Step components
className	string	CSS class for styling

ProgressBar

Visualizes progress through the form steps.

Prop	Type	Description
type	"dot" | "bar" | "dashed"	Type of progress indicator
className	string	CSS class for styling
fillColor	string	Color for completed sections (default: "bg-blue-500")
trackColor	string	Color for incomplete sections (default: "bg-gray-300")
height	string	Height of the bar (default: "h-2")
dotColor	string	Color for completed dots (default: "bg-blue-500 border-blue-500")
inactiveDotColor	string	Color for incomplete dots (default: "bg-white border-gray-300")
connectorColor	string	Color for dot connectors (default: "bg-gray-300")
dotSize	string	Size of dots (default: "w-3 h-3")
dashedGap	string	Gap between dashed segments (default: "gap-1")
dashedSegmentRadius	string	Border radius of dashed segments (default: "rounded")

StepControls

Container for navigation buttons.

Prop	Type	Description
children	ReactNode	Button components
className	string	CSS class for styling

NextButton, PrevButton, SubmitButton

Navigation buttons for the form.

Prop	Type	Description
children	ReactNode	Button content
className	string	CSS class for styling
onClick	(event: React.MouseEvent<HTMLButtonElement>) => void	Click handler

useMultistepForm

Hook to access the multi-step form context.

1const { 
2  currentStepIndex,
3  currentStepKey,
4  stepFields,
5  setStepFields,
6  nextStep,
7  prevStep,
8  submit,
9  steps
10} = useMultistepForm();

Return Value	Type	Description
currentStepIndex	number	Index of the current step
currentStepKey	string	Key of the current step
stepFields	Record<string, string[]>	Map of step keys to field names
setStepFields	React.Dispatch<React.SetStateAction<Record<string, string[]>>>	Function to update step fields
nextStep	() => void	Function to navigate to the next step
prevStep	() => void	Function to navigate to the previous step
submit	() => void	Function to submit the form
steps	string[]	Array of step keys

Progress Visualization

The ProgressBar component offers three different styles:

Bar Type

1<ProgressBar type="bar" />

A continuous progress bar that fills based on the current step.

Dot Type

1<ProgressBar type="dot" />

Dots connected by lines, with completed steps highlighted.

Dashed Type

1<ProgressBar type="dashed" />

Segmented bar with each segment representing a step.

Customization

All components accept a className prop for styling. You can use this to apply your own styles or integrate with CSS frameworks like Tailwind CSS.

For buttons, you can either provide a string as children (which will use default styling) or pass a custom button component:

1// Using default styling
2<NextButton>Next</NextButton>
3
4// Using custom button
5<NextButton>
6  <button className="my-custom-button">
7    Next <ArrowRightIcon />
8  </button>
9</NextButton>

Contributing

Contributions are welcome! Here's how you can contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to update tests as appropriate and adhere to the existing coding style.

License

This project is licensed under the MIT License - see the LICENSE file for details.