Advanced and multi-feature react stepper component designed to be incredibly versatile for a variety of workflows and use cases.
npm install react-dynamic-stepper[![Storybook][badge_storybook]][package_link]
[![Npm version][badge_npm-version]][package_link]
[![Npm downloads][badge_npm-downloads]][package_link]
[![Npm minified][badge_npm-minified]][package_link]
[![Npm CICD][badge_npm-cicd]][package_link]
Advanced and multi-feature stepper component designed to be incredibly versatile for a variety of workflows and use cases.
It supports the following features:
- Horizontal stepper UI.
- Vertical stepper UI.
- Inline stepper UI.
- Sequence stepper.
- Right to left languages.
- Custom pallet.
- Custom header.
- Custom footer.
- Navigate to the required step programmatically.
Checkout the demo of this package on [codepen][package_demo-link]
- Via npm:
``shell`
npm install react-dynamic-stepper
- Via yarn:shell`
yarn add react-dynamic-stepper
- Via pnpm:shell`
pnpm add react-dynamic-stepper
`jsx
import { Stepper } from 'react-dynamic-stepper';
const App = () => {
const steps = [
{
header: {
label: 'Step 1',
},
content:
const submitStepper = () => {
console.log('submitted');
};
return (
footerData={{
submitBtn: {
onClickHandler: submitStepper,
},
}}
/>
);
};
`
| Prop | Type | Default | Required | Description |
|------------------------------|--------------------------------|---------| --- |---------------------------------------------------------------------------------------------------------------------------------------|
| isRightToLeftLanguage | Boolean | false | No | If true, sets the direction of the stepper to rtl |false
| isVertical | Boolean | | No | If true, sets the orientation of the stepper to vertical |false
| isInline | Boolean | | No | If true, sets the header display of the stepper to inline |false
| isSequenceStepper | Boolean | | No | If true, sets the stepper to sequence mode (forces the user to complete steps in sequence) |true
| isStepConnector | Boolean | | No | If false, removes the step connector |null
| customConnector | ReactNode | | No | Custom connector element to display between steps (only shows when isStepConnector is true) |false
| disableStepHeaderClick | Boolean | | No | If true, disables clicking on step headers (indicator and label) to navigate directly to completed or error steps |useRef
| ref | | null | No | It exposes navigateToStepByIndex and navigateToStepById functions, that can programmatically navigate the user to a specific step |
| steps | [StepInterface[]](#StepInterface) | - | Yes | Array of steps |
| footerData | [FooterDataInterface[]](#FooterDataInterface) | - | Yes | Footer data |
| pallet | [PalletInterface[]](#PalletInterface) | - | No | Pallet for custom color codes |
| Prop | Type | Default | Required | Description |
|--------------------------------------------|-------------------------------------------------|--------------------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------|
| id | String | - | No | Unique identifier for the step (required when using navigateToStepById) |
| header.label | String | - | Yes | The label to display on the step header |
| header.indicator | ReactNode | Step number | No | Custom indicator for the step |
| header.isKeepIndicatorOnComplete | Boolean | false | No | Keep header indicator when step is completed |Continue to ${nextStepLabel}
| footer.nextBtn.label | String | or Submit | No | Set next button label of the current step |undefined
| footer.nextBtn.className | String | | No | CSS classname(s) to be applied to next button of the current step |false
| footer.nextBtn.isPreventNextClick | Boolean | | No | If true, clicking the 'Next' or 'Submit' button for the current step will not trigger any action unless its set to false |() => void
| footer.nextBtn.onClickHandler | Function: or () => Promise | - | No | Invoked when the next button of the current step is clicked |Back to ${prevStepLabel}
| footer.prevBtn.label | String | | No | Set prev button label of the current step |undefined
| footer.prevBtn.className | String | | No | CSS classname(s) to be applied to prev button of the current step |false
| content | ReactNode | - | Yes | The content to display for the step |
| isLoading | Boolean | | No | If true, the 'Next' button will be disabled |false
| isError | Boolean | | No | If true, will display the step with error UI |false
| isWarning | Boolean | | No | If true, will display the step with warning UI |false
| isComplete | Boolean | | Yes | If true, will display the step with completed UI and enables 'Next' button |
| Prop | Type | Default | Required | Description |
| --- | --- |--------------------------------|--- |----------------------------------------------------------------------|
| prevBtn.label | String | Back to ${prevStepLabel} | No | Label for the prev button |undefined
| prevBtn.className | String | | No | CSS classname(s) to be applied to prev button |Continue to ${nextStepLabel}
| nextBtn.label | String | | No | Label for the next button |undefined
| nextBtn.className | String | | No | CSS classname(s) to be applied to next button |Submit
| submitBtn.label | String | | No | Label for submit button in the last step |undefined
| submitBtn.className | String | | No | CSS classname(s) to be applied to the submit button in the last step |() => void
| submitBtn.onClickHandler | Function: or () => Promise | - | Yes | Invoked when the submit button is clicked |
| Prop | Type | Default | Required | Description |
|----------| --- | --- | --- |----------------------------|
| default | String | #627c90 | Yes | Default color code |#f1c40f
| warning | String | | Yes | Color code for warning UI |#e95a4b
| danger | String | | Yes | Color code for error UI |#4caf50
| success | String | | Yes | Color code for success UI |#e3e8ec
| disabled | String | | Yes | Color code for disabled UI |
The ref passed to the Stepper component exposes two navigation functions that can programmatically navigate the user to a specific step. It can be useful in scenarios when controlling step navigation from outside the Stepper component is required.
- navigateToStepByIndex(index: number): Navigate to a step using its zero-based index position
- navigateToStepById(id: string): Navigate to a step using its unique identifier (requires the step to have an id property)
> ### Important Note:
>
> Make sure to mark the required steps as completed if you want to navigate programmatically so that you can submit your stepper. This ensures that all necessary steps have been taken before the finish line.
JavaScript
`jsx
import { useRef } from 'react';
import { Stepper } from 'react-dynamic-stepper';
const App = () => {
const stepperRef = useRef(null);
const steps = [
{
id: 'step-1',
header: { label: 'Step 1' },
content:
return (
<>
stepperRef.current?.navigateToStepByIndex(1);
}}
>
Navigate to step 2 by index
stepperRef.current?.navigateToStepById('step-2');
}}
>
Navigate to step 2 by ID
steps={steps}
/ OTHER PROPS /
/>
);
};
`TypeScript
`typescript jsx
import { useRef } from 'react';
import { Stepper, StepperRef, StepInterface } from 'react-dynamic-stepper';
const App = () => {
const stepperRef = useRef
const steps: StepInterface[] = [
{
id: 'step-1',
header: { label: 'Step 1' },
content:
return (
<>
stepperRef.current?.navigateToStepByIndex(1);
}}
>
Navigate to step 2 by index
stepperRef.current?.navigateToStepById('step-2');
}}
>
Navigate to step 2 by ID
steps={steps}
/ OTHER PROPS /
/>
);
};
`
- step.footer.nextBtn.onClickHandler => This is invoked when the 'Next' button of the current step is clicked.onClickHandler
- If your returns a Promise and you want to navigate to the next step only if the Promise resolves successfully, you need to throw error inside the catch block:`typescript``
const submitCurrentStep = async () => {
try {
/ Your business logic here /
} catch (error) {
throw error;
} finally {
/ Cleanup code here /
}
};
- [Changelog][changelog]
[changelog]: https://github.com/DonAdam2/react-dynamic-stepper/blob/main/CHANGELOG.md
[badge_npm-version]: https://img.shields.io/npm/v/react-dynamic-stepper.svg
[badge_npm-downloads]: https://img.shields.io/npm/dm/react-dynamic-stepper.svg
[badge_npm-minified]: https://img.shields.io/bundlejs/size/react-dynamic-stepper
[badge_npm-cicd]: https://github.com/DonAdam2/react-dynamic-stepper/actions/workflows/publish.yml/badge.svg
[badge_storybook]: https://cdn.jsdelivr.net/gh/storybookjs/brand@master/badge/badge-storybook.svg
[package_link]: https://npmjs.org/package/react-dynamic-stepper
[package_demo-link]: https://codepen.io/AdamMorsi/pen/qBRazPM