react-wiz
A general purpose wizard component creator for React.
Check out the live demo here
A creator function is exported that takes a pure react component to wrap each wizard step as an optional argument and returns a component class to be used as the wizard. The Component handles wizard logic and rendering is left to the user for flexibility.
Installation
npm install --save https://github.com/DAIAD/react-wizard.git
Usage
The wizard accepts the following options
Option | Type | Description |
---|---|---|
onComplete | func | onComplete callback function to execute |
promiseOnNext | bool | option to return promise in onNextClicked function |
validateLive | bool | option to validate on user-input, otherwise only on next |
initialActive | string | pass step id to start from step other than first. Note that a valid path to step id given initialValues must exist. |
childrenProps | object | object that is passed as props to all children |
children | oneOfType([ arrayOf(element), object]).isRequired |
wizard step components |
Each child passed to Wizard must be a React Component that handles the rendering and interaction of the relative step. Each child accepts the following options
Option | Type | Description |
---|---|---|
id | string.isRequired | required id. Note that id = 'complete' is reserved |
title | string | title of the step. Useful when a component wrapper is provided |
description | string | description of the step. Useful when a component wrapper is provided |
initialValue | any.isRequired | initialValue required to define return value expected type |
validate | func | function to validate input of the step. Must throw string ex. value => !value ? throw 'Error' : null |
next | func | The next function that allows changing the default flow of the wizard based on the value provided. Default next returns the next item. ex. value => value == 1 ? 'id1' : 'id2' |
The following properties are passed down to each component and wrapper component (if provided) for full control of each step
Property | Type | Description |
---|---|---|
onNextClicked | func | next click handler |
onPreviousClicked | func | previous click handler |
onComplete | func | on complete handler that executes the provided onComplete callback function with values object and sets wizard as completed, ex. values => handleValues(values) |
reset | func | reset handler |
setValue | func | the callback function to set the wizard item value, ex. () => setValue('check'), or setValue([1,2,3]), or setValue({a:1, b:2}) |
value | any | the value set by setValue (initially initialValue) |
values | object | the cleared wizard values with wizard items ids as keys, ex. {'step1': 'check', 'step2': [1,2,3]} |
errors | string | any validation errors |
completed | bool | is wizard complete |
steps | arrayOf(object) | array of all steps objects (based on the current flow) containing id (string), title (string), index (number), cleared (bool), active (bool) |
step | object | the active step object |
isActive | bool | is wizard item active (by default only active is displayed) |
isLast | bool | is the last wizard item |
hasNext | bool | wizard item has next |
hasPrevious | bool | wizard item has previous |
All types are React PropTypes https://facebook.github.io/react/docs/typechecking-with-proptypes.html
Example
A simple wizard example is shown here
import createWizard from 'react-wiz';
const Wizard = createWizard();
function Step1 (props) {
const { value, setValue, errors, onNextClicked } = props;
return (
<div>
<h3>Hello world</h3>
<p>Write your name</p>
<input onChange={e => setValue(e.target.value)} placeholder="Input" value={value} />
{ errors ? <div><br /><span>Validation fail: {errors}</span></div> : <div /> }
<button onClick={onNextClicked} style={{float: 'right'}}>Next</button>
</div>
);
}
function Step2 (props) {
const { values, onPreviousClicked, onComplete } = props;
return (
<div>
<p>Are you sure you want to submit, {values.name ? values.name.values : ''}?</p>
<button onClick={onPreviousClicked} style={{float: 'left'}}>Previous</button>
<button onClick={onComplete} style={{float: 'right'}}>Submit</button>
</div>
);
}
function WizardExample (props) {
return (
<Wizard
onComplete={values => { alert(`Wizard complete: \n ${JSON.stringify(values)}`); }}
>
<Step1
id='name'
initialValue=''
validate={value => { if (!value) { throw 'No name provided'; } }}
/>
<Step2
id='confirm'
/>
</Wizard>
To run locally:
npm run start
To run tests:
npm run test
Requires node >= 4.3.2