react-wizard-primitive - npm explorer

Zero dependencies scaffold for a wizard / stepper without any UI restrictions. Hooks and render props API available!

![Build](https://travis-ci.org/Jibbedi/react-wizard-primitive)
![Coverage](https://codecov.io/gh/Jibbedi/react-wizard-primitive)
![License](https://github.com/Jibbedi/react-wizard-primitive/blob/master/LICENSE)
![Version](https://www.npmjs.com/package/react-wizard-primitive)
![Types](https://www.npmjs.com/package/react-wizard-primitive)
![Size](https://www.npmjs.com/package/react-wizard-primitive)
![Dependencies](https://www.npmjs.com/package/react-wizard-primitive)
![Pull Requests welcome](http://makeapullrequest.com/)
![Downloads](https://www.npmjs.com/package/react-wizard-primitive)
![semantic-release](https://github.com/semantic-release/semantic-release)

![github stars](https://github.com/Jibbedi/react-wizard-primitive)

- The Problem
- The Solution
- Quick Start
- Splitting the wizard in multiple components
- Building your own abstractions
- API
- Step
- useWizard
- Example
- useWizardStep
- Example
- Wizard
- Example
- WizardStep
- Example
- Routing
- Basics
- Initial Hash Route
- Example
- Examples
- 🔗 Basic Hooks
- 🔗 Basic Render Props
- 🔗 Buildup Wizard
- 🔗 Custom Abstraction
- Migration from older versions
- Upgrading from v1
- Contributors

The Problem

You need to implement a wizard / stepper, but have specific UI requirements.
You want a flexible solution that suits a wide range of use cases. Check out the examples to see what's possible.

The Solution

React Wizard Primitive handles the state management and you bring the UI.
Leverage a render props or hooks API to get rid of the tedious boilerplate.
You can use this library to build other abstractions, that better suit your specific needs on top of it.

Quick Start

1. Install react-wizard-primitive

``bash npm i react-wizard-primitive`

2. Create your first wizard


  Hooks API

`jsx import React from "react"; import { useWizard } from "react-wizard-primitive";

export default function App() { const { getStep, nextStep } = useWizard(); const stepTitles = ["First", "Second", "Third"]; //let's render them one ofter the other

return (


      {stepTitles.map(
        (stepTitle) =>
          getStep().isActive && {stepTitle}

      )}


  );
}


See a working example here.


  Render Props API

`jsx import React from "react"; import { Wizard } from "react-wizard-primitive";

export default function App() { const stepTitles = ["First", "Second", "Third"]; //let's render them one ofter the other

return ( {({ getStep, nextStep }) => (


          {stepTitles.map(
            (stepTitle) =>
              getStep().isActive && {stepTitle}

          )}


      )}
    
  );
}


See a working example here.

`Splitting the wizard in multiple components`

Using the getStep function is great if you are creating a small wizard which can live inside a single component.

If your wizard grows it can come in handy to separate each step inside it's own component.react-wizard-primitive makes this really easy.

1. Put a WizardComponent as your wizard root 2. Create Step components. All step components inside one Wizard Component work together.


  Hooks API

`jsx import React from "react"; import { Wizard, useWizardStep } from "react-wizard-primitive";

const FirstStep = () => { const { isActive, nextStep } = useWizardStep(); return isActive ?

First Step

 : null;
};
const SecondStep = () => {
  const { isActive, nextStep } = useWizardStep();
  return isActive ? 
Second Step
 : null;
};
export default function App() {
  return (
    
      
      {/ a step doesn't need to be a direct child of the wizard. It can be nested inside of html or react components, too!/}
      

        
      

    
  );
}


See a working example here.


  Render Props API

`jsx import React from "react"; import { Wizard, WizardStep } from "react-wizard-primitive";

const FirstStep = () => { return ( {({ isActive, nextStep }) => isActive ?

First Step

 : null
      }
    
  );
};
const SecondStep = () => {
  return (
    
      {({ isActive, nextStep }) =>
        isActive ? 
Second Step
 : null
      }
    
  );
};
export default function App() {
  return (
    
      
      {/ a step doesn't need to be a direct child of the wizard. It can be nested inside of html or react components, too!/}
      

        
      

      {/ WizardStep can also be used without placing it inside another component/}
      
        {({ isActive }) => (isActive ? Third Step
 : null)}
      
    
  );
}


See a working example here.

`Building your own abstractions`

Sometimes you need a wizard in multiple places, but keep the styling consistent.react-wizard-primitive provides you with basic building blocks that you can use to build powerful abstractions on top of it.

`jsx

Just some other inline jsx


  
  
    And another one

  
  
    Last one


See a working example here.
API
$3

A step is the main data structure for the wizard. It is returned by the getStep call and provided by useWizardStep and the WizardStep component.

- _index_ number> The index of the current step - _isActive_boolean> Is the state the currently active one? - _hasBeenActive_boolean> Has the step been active before? - _nextStep_function> Move to the step _after_ this step. - _previousStep_function> Move to the step _before_ this step. - _resetToStep_function> Set this step to be currently active. Set hasBeenActive for all following steps to false. - _moveToStep_function> Set this step to be currently active. All following steps will keep the activated state. - _goToStep_function(index:number)> Go to the step with the given index

`$3`

A hook that manages the state of the wizard and provides you with functions to interact with it

Arguments

- _options_ object (optional)

- _initialStepIndex_ number (optional)

> The provided step index will be displayed initially. All previous steps will be treated as if they've been already activated.

- _onChange_ function({newStepIndex : number, previousStepIndex: number, maxActivatedStepIndex : number})(optional) > Is called every time the wizard step changes.

Returns

- _wizard_ object- _getStep_function(options?) : Step> Creates a wizard step and provides it's current state. It can take an optional options object, which can take arouteTitleSee routing for more details. - _activeStepIndex_number> Currently active step - _maxActivatedStepIndex_number> Index of the furthest step, that has been activated - _maxActivatedStepIndex_number> Index of the furthest step, that has been activated - _nextStep_function> Call this to proceed to the next step - _previousStep_function> Call this to proceed to the previous step - _moveToStep_function(stepIndex : number, options? : {skipOnChangeHandler?: boolean})> Move to step with index _stepIndex_. You can pass in options to control if the _onChange_ handler should be called for this operation. - _resetToStep_function(stepIndex : number, options? : {skipOnChangeHandler?: boolean})> Move to step with index _stepIndex_. Set _hasBeenActive_ for all following steps as well as the new step to false. You can pass in options to control if the _onChange_ handler should be called for this operation.

#### Example

`jsx // start at third step and log every change const { getStep } = useWizard({ initialStepIndex: 2, onChange: ({ newStepIndex, previousStepIndex }) => { console.log(I moved from step ${previousStepIndex} to ${newStepIndex}); }, });`

`$3`

A hook that let's you split your wizard into separate components and creates a wizard step. It calls getStep under the hood.

Arguments

- _options_ WizardStepOptions(optional) > It can take an optional options object, which can take arouteTitle See routing for more details.

Returns

- A Step object

#### Example

`jsx // isActive will be true if this wizardStep should be rendered, nextStep will move to the next step const { isActive, nextStep } = useWizardStep();`

`$3`

A component that servers as the root for a wizard if you choose to split your wizard into multiple components.

Otherwise it can be used as a replacement for the useWizardhook. It takes the same arguments (as props) and returns the same values to the render prop.

#### Example

`jsx // start at third step and log every change { console.log(I moved from step ${previousStepIndex} to ${newStepIndex}); }}> { ({getStep}) => { ... } }`

`$3`

A component that serves as an alternative to the useWizardStephook. It takes the same arguments (as props) and returns the same values to the render prop.

#### Example

`jsx // isActive will be true if this wizardStep should be rendered, nextStep will move to the next step { ({isActive, nextStep}) => { ... } }`

`Routing`

`$3`

Out of the box react-wizard-primitive supports an opt-in routing via hash.

In order to use it, you need to specify a routeTitle in the getStep call or pass it as a prop to the _WizardStep_ or _useWizardStep_ hook. The routeTitle will be used as the hash.

If no routeTitle is provided, react-wizard-primitive won't make any changes to the URL. If only some steps are provided with a title, we assume that this happened by mistake, and won't change the url either. Instead we log a warning to the console, indicating which steps are missing a title.

`$3`

If a hash is present when the wizard is first rendered, it will try to find a matching step to that hash and jump to it or otherwise jump to the initial step.

You can use this behaviour to start the wizard at any given point.

`$3`

`jsx {"yourdomain.com/#/first-step"} {({ isActive, nextStep }) => isActive &&

Step 1


    }
  
  {"yourdomain.com/#/second-step"}
  
    {({ isActive, nextStep }) =>
      isActive && 
Step 2

    }
  
  {"yourdomain.com/#/third-step"}
  
    {({ isActive, nextStep }) =>
      isActive && 
Step 3

    }


Examples
You can build nearly anything on top of react-wizard-primitive.
Take a look at those examples to get an idea of what's possible.
$3
> This is a good starting point, if you want to see a basic hook implementation.
> A classical wizard, which displays the steps one after the other.
!Basic Example
$3
> Same example, but implemented with the render props API.
$3
> This example demonstrates, how you can build a wizard that displays the steps one after another, but keeps the already displayed steps around.
!Buildup Wizard
$3
> It can get tedious to work with the basic building blocks and repeat styling or display handling all over again. This example demonstrates how you can build your own abstractions on top of react-wizard-primitive.

`jsx

Just some other inline jsx


  
  
    And another one

  
  
    Last one


!Buildup Wizard
Migration from older versions
$3

- hasBeenActive is now false on first render. To achieve the previous behavior you can modify your code to hasBeenActive || isActive-maxVisitedStepIndex has been renamed to maxActivatedStepIndex and will not include the currently active step if it's first rendered. To achieve the previous behavior you can modify your code to Math.max(maxActivatedStepIndex, activeStepIndex)

`Contributors`

_{Johannes Kling}
💻 📖 🤔 💡 ⚠️

_{Jose Miguel Bejarano}
🤔

_kaYcee
🤔

_{Kevin Aldebert}
🤔

_{Carlos Santos}
🐛

_{Andrei Benea}
🐛

Zero dependencies scaffold for a wizard / stepper without any UI restrictions. Hooks and render props API available!

![github stars](https://github.com/Jibbedi/react-wizard-primitive)

The Problem

You need to implement a wizard / stepper, but have specific UI requirements.
You want a flexible solution that suits a wide range of use cases. Check out the examples to see what's possible.

The Solution

Quick Start

1. Install react-wizard-primitive

``bash npm i react-wizard-primitive`

2. Create your first wizard


  Hooks API

`jsx import React from "react"; import { useWizard } from "react-wizard-primitive";

export default function App() { const { getStep, nextStep } = useWizard(); const stepTitles = ["First", "Second", "Third"]; //let's render them one ofter the other

return (


      {stepTitles.map(
        (stepTitle) =>
          getStep().isActive && {stepTitle}

      )}


  );
}


See a working example here.


  Render Props API

`jsx import React from "react"; import { Wizard } from "react-wizard-primitive";

export default function App() { const stepTitles = ["First", "Second", "Third"]; //let's render them one ofter the other

return ( {({ getStep, nextStep }) => (


          {stepTitles.map(
            (stepTitle) =>
              getStep().isActive && {stepTitle}

          )}


      )}
    
  );
}


See a working example here.

`Splitting the wizard in multiple components`

Using the getStep function is great if you are creating a small wizard which can live inside a single component.

If your wizard grows it can come in handy to separate each step inside it's own component.react-wizard-primitive makes this really easy.

1. Put a WizardComponent as your wizard root 2. Create Step components. All step components inside one Wizard Component work together.


  Hooks API

`jsx import React from "react"; import { Wizard, useWizardStep } from "react-wizard-primitive";

const FirstStep = () => { const { isActive, nextStep } = useWizardStep(); return isActive ?

First Step

 : null;
};
const SecondStep = () => {
  const { isActive, nextStep } = useWizardStep();
  return isActive ? 
Second Step
 : null;
};
export default function App() {
  return (
    
      
      {/ a step doesn't need to be a direct child of the wizard. It can be nested inside of html or react components, too!/}
      

        
      

    
  );
}


See a working example here.


  Render Props API

`jsx import React from "react"; import { Wizard, WizardStep } from "react-wizard-primitive";

const FirstStep = () => { return ( {({ isActive, nextStep }) => isActive ?

First Step

 : null
      }
    
  );
};
const SecondStep = () => {
  return (
    
      {({ isActive, nextStep }) =>
        isActive ? 
Second Step
 : null
      }
    
  );
};
export default function App() {
  return (
    
      
      {/ a step doesn't need to be a direct child of the wizard. It can be nested inside of html or react components, too!/}
      

        
      

      {/ WizardStep can also be used without placing it inside another component/}
      
        {({ isActive }) => (isActive ? Third Step
 : null)}
      
    
  );
}


See a working example here.

`Building your own abstractions`

`jsx

Just some other inline jsx


  
  
    And another one

  
  
    Last one


See a working example here.
API
$3

A step is the main data structure for the wizard. It is returned by the getStep call and provided by useWizardStep and the WizardStep component.

`$3`

A hook that manages the state of the wizard and provides you with functions to interact with it

Arguments

- _options_ object (optional)

- _initialStepIndex_ number (optional)

> The provided step index will be displayed initially. All previous steps will be treated as if they've been already activated.

- _onChange_ function({newStepIndex : number, previousStepIndex: number, maxActivatedStepIndex : number})(optional) > Is called every time the wizard step changes.

Returns

#### Example

`$3`

A hook that let's you split your wizard into separate components and creates a wizard step. It calls getStep under the hood.

Arguments

- _options_ WizardStepOptions(optional) > It can take an optional options object, which can take arouteTitle See routing for more details.

Returns

- A Step object

#### Example

`jsx // isActive will be true if this wizardStep should be rendered, nextStep will move to the next step const { isActive, nextStep } = useWizardStep();`

`$3`

A component that servers as the root for a wizard if you choose to split your wizard into multiple components.

Otherwise it can be used as a replacement for the useWizardhook. It takes the same arguments (as props) and returns the same values to the render prop.

#### Example

`jsx // start at third step and log every change { console.log(I moved from step ${previousStepIndex} to ${newStepIndex}); }}> { ({getStep}) => { ... } }`

`$3`

A component that serves as an alternative to the useWizardStephook. It takes the same arguments (as props) and returns the same values to the render prop.

#### Example

`jsx // isActive will be true if this wizardStep should be rendered, nextStep will move to the next step { ({isActive, nextStep}) => { ... } }`

`Routing`

`$3`

Out of the box react-wizard-primitive supports an opt-in routing via hash.

In order to use it, you need to specify a routeTitle in the getStep call or pass it as a prop to the _WizardStep_ or _useWizardStep_ hook. The routeTitle will be used as the hash.

`$3`

If a hash is present when the wizard is first rendered, it will try to find a matching step to that hash and jump to it or otherwise jump to the initial step.

You can use this behaviour to start the wizard at any given point.

`$3`

`jsx {"yourdomain.com/#/first-step"} {({ isActive, nextStep }) => isActive &&

Step 1


    }
  
  {"yourdomain.com/#/second-step"}
  
    {({ isActive, nextStep }) =>
      isActive && 
Step 2

    }
  
  {"yourdomain.com/#/third-step"}
  
    {({ isActive, nextStep }) =>
      isActive && 
Step 3

    }


Examples
You can build nearly anything on top of react-wizard-primitive.
Take a look at those examples to get an idea of what's possible.
$3
> This is a good starting point, if you want to see a basic hook implementation.
> A classical wizard, which displays the steps one after the other.
!Basic Example
$3
> Same example, but implemented with the render props API.
$3
> This example demonstrates, how you can build a wizard that displays the steps one after another, but keeps the already displayed steps around.
!Buildup Wizard
$3
> It can get tedious to work with the basic building blocks and repeat styling or display handling all over again. This example demonstrates how you can build your own abstractions on top of react-wizard-primitive.

`jsx

Just some other inline jsx


  
  
    And another one

  
  
    Last one


!Buildup Wizard
Migration from older versions
$3

`Contributors`

_{Johannes Kling}
💻 📖 🤔 💡 ⚠️

_{Jose Miguel Bejarano}
🤔

_kaYcee
🤔

_{Kevin Aldebert}
🤔

_{Carlos Santos}
🐛

_{Andrei Benea}
🐛