Your module to handle with Form Wizards in ReactJS applications easier.
Well, there are several selling points, actually!
- 🤘 Full Typescript support: It embraces Typescript for real! It accepts interfaces and types as generics for their data structures and more!
- 🏆 Better Developer Experience (DX): It enforces some conventions in order to make sure we got you covered! Issues with things such as specific components that needs to be used, which component is incorrect and context that needs to be used as wrapper will be raised straightaway on development environment.
- 🎯 Covers different usage and scenarios: It covers simple usage, but also covers scenarios when you have steps being added dinamically, specific validation steps that needs to be added, data structures that should be passed on, etc. The sky is the limit here!
- 🤩 No external dependencies: And that's exactly what you read. This is a zero-dependencies package, so you can integrate with Material-UI, Chakra-UI or any other Design System you might be using - including your own. Feel free to integrate with your workflow as you wish
- 🗜 Small bundle: about 1.48 KB gzipped (ESM and CJS), with a 1.6 KB budget checked on every CI run by
size-limit
Requires React 18 or later (react as a peer dependency) and Node 22 or later. React 17 users should stay on 2.x.
You can get it on NPM installing react-sweet-wizard module as a project dependency.
npm install react-sweet-wizard --save
# or
yarn add react-sweet-wizardYou'll need to import WizardProvider and add it into the root component of your application. So that you can create your wizard steps by using Steps, Step and control them via useWizardContext hook.
import {
useWizardContext,
WizardProvider,
Steps,
Step,
} from 'react-sweet-wizard';
const Progress = () => {
const { activeStepIndex, steps } = useWizardContext();
return (
<div>
State {activeStepIndex + 1} of {steps.length}
</div>
);
};
const WizardSteps = () => (
<Steps>
{/* `id` can be a number or a string */}
<Step key={0} id={0}>
<div>
<p>step 1</p>
</div>
</Step>
<Step key="1" id="1">
<div>
<p>step 2</p>
</div>
</Step>
<Step key="step3" id="step3">
<div>
<p>step 3</p>
</div>
</Step>
</Steps>
);
const App = () => (
<WizardProvider>
<Progress />
<WizardSteps />
</WizardProvider>
);
export default App;Try out the demo on Stackblitz!
React Sweet Wizard Playground!
$ npm test$ npm run build$ npm run size$ npm run lintThis package exposes a hook with a few different methods which you can interact.
The hook accepts a generic as data structure. If you don't pass anything, it will use DefaultWizardStepProps as default one. Otherwise, it will use the one you defined.
To define a new interface and pass as a generic you should extends from
DefaultWizardStepProps
import { useWizardContext, DefaultWizardStepProps } from 'react-sweet-wizard';
...
// Creating a data structure interface
// To be used for steps
interface MyWizardSteps extends DefaultWizardStepProps {
name: string;
};
...
// Yay! You can use generics to enforce the data structure
// used for steps
const ctx = useWizardContext<MyWizardSteps>();
// ✨ where the magic happens ✨steps: You can check how many steps are available on the wizard. Interesting to be used if you're adding dynamic nodes, as an exampleactiveStepIndex: A number referencing which step is visible on your wizardisFirstStep: A boolean that can be used to check if the current step is the first one on your wizardisLastStep: A boolean that can be used to check if the current step is the last one on your wizard
Sets a new value for steps to be used and accessed across components. It covers scenarios such as steps with complex data structures. Steps registered automatically by <Steps> carry only id, so declare your extra fields optional or call setSteps before reading them; the data you set is kept as long as the step ids match the <Step> children.
It will use the defined Generic interface for it. Otherwise, it follows DefaultWizardStepProps interface.
import { useWizardContext, DefaultWizardStepProps } from 'react-sweet-wizard';
// Creating a data structure interface
// To be used for steps
interface MyWizardSteps extends DefaultWizardStepProps {
name: string;
};
...
// Yay! You can use generics to enforce the data structure
// used for steps
const { setSteps } = useWizardContext<MyWizardSteps>();
// Updating the mapped steps
setSteps([
{ id: 0, name: 'first'},
{ id: 1, name: 'second'},
{ id: 'step3', name: 'third'},
]);
...Returns a data structure value for the current step to be used and accessed across components. It covers scenarios such as steps with complex data structures.
It will use the defined Generic interface for it. Otherwise, it follows DefaultWizardStepProps interface.
import { useWizardContext } from 'react-sweet-wizard';
...
// Yay! You can use generics to enforce the data structure
// used for steps
const { getActiveStep, onNext } = useWizardContext();
// Adding 3 steps
setSteps([
{ id: 0 },
{ id: 1 },
{ id: 'step3' },
]);
// Returns the first step since the wizard is following the common flow
// { id: 0 }
getActiveStep();
// Moving wizard to the second step
onNext();
// Returns the second step
// { id: 1 }
getActiveStep();
...Moves the wizard to the next step and returns a promise that resolves after the move. It also accepts a callback, sync or async, that runs before the move; if the callback throws or rejects, the wizard stays on the current step and the promise rejects with that error. E.G.
import { useWizardContext } from 'react-sweet-wizard';
// Creating a data structure interface
// To be used for steps
interface MyWizardSteps extends DefaultWizardStepProps {
name: string;
};
...
// Yay! You can use generics to enforce the data structure
// used for steps
const { setSteps, onNext } = useWizardContext<MyWizardSteps>();
...
// Adding 3 steps
setSteps([
{ id: 0, name: 'first'},
{ id: 1, name: 'second'},
{ id: 'step3', name: 'third'},
]);
// Moving wizard to the second step
onNext();
onNext(() => {
alert('And here we go! 🚀');
// You can add a specific validation here!
});
// Async validation: the wizard only advances when the callback resolves
try {
await onNext(async () => {
await validateCurrentStep();
});
} catch (error) {
// validation failed; still on the same step
}Moves the wizard to the previous step.
import { useWizardContext } from 'react-sweet-wizard';
...
// Yay! You can use generics to enforce the data structure
// used for steps
const { setSteps, onPrevious } = useWizardContext();
...
// Adding 2 steps
setSteps([
{ id: 0},
{ id: 1},
]);
// Moving wizard to the second step
onNext();
// Moving wizard back to the first step
onPrevious();Moves the wizard to a specific step. A number is the step index (goTo(1) is always the second step); a string is matched against the step id (goTo('step3'), and goTo('10') finds <Step id={10}>). A numeric argument is never matched against ids, so pass a numeric id as a string. Out-of-range calls are ignored.
import { useWizardContext, DefaultWizardStepProps } from 'react-sweet-wizard';
// Creating a data structure interface
// To be used for steps
interface MyWizardSteps extends DefaultWizardStepProps {
name: string;
};
...
// Yay! You can use generics to enforce the data structure
// used for steps
const { setSteps, goTo, getActiveStep } = useWizardContext<MyWizardSteps>();
...
// Updating the mapped steps
setSteps([
{ id: 0, name: 'first'},
{ id: 1, name: 'second'},
{ id: 'step3', name: 'third'},
]);
// Moving wizard to second step
goTo(1);
// Output
// { id: 1, name: 'second'}
// It's using `MyWizardSteps` interface, so don't worry
console.log(getActiveStep());
// Moving wizard to third step
goTo('step3');
// Output
// { id: 'step3', name: 'third'}
console.log(getActiveStep());Releases are cut with npm version <patch|minor|major> (it runs lint, types and tests, then moves the ## [Unreleased] changelog entries under the new version), followed by pushing the commit and its tag (git push --follow-tags), which triggers the GitHub Release workflow, and a manual npm publish (its prepack script runs the checks again and builds dist/).
Wilson Mendes (willmendesneto)