/react-wizard

A general purpose wizard component creator for React

Primary LanguageJavaScriptGNU Lesser General Public License v3.0LGPL-3.0

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