use-wizard

Use a wizard Harry

The React.JS hook useWizard is an easy-to-use state manager that handles multi-paths, multi-steps wizards and navigate through them.

Real-life examples :

• A basic example for a linear wizard with numbers: use-wizard-1
• A linear wizard with strings: use-wizard-1
• A non-linear wizard: link to come
• An example with conditional steps: link to come

What does it do ?

• It handles the creation of multi-steps and multi-paths complex wizards in a simple declarative way,
• It allows your user to navigate through them through useful method,
• It gives you the ability to generate custom wizards for your users,
• It makes refactoring / maintaining your wizard extremely easy.

The 3 kind of wizards

Below you will find 3 examples. Each of them describe a different way of declaring your wizard.

• The linear wizard with numbers: each step is a number, it starts with step 1.
• The linear wizard with strings: you have to initialize your wizard with an array of strings, each of them being a different step. The first one is the first step.
• The nested wizard: this one allows you to define wizards with nested routes.

Installing and initializing it

Install it

npm i use-wizard

Import it

const useWizard = require('use-wizard');

or

import {useWizard} from "use-wizard";

Declare useWizard like any other hook

// For a linear wizard with numbers
const [step, wizard] = useWizard(); 

or

// For a linear wizard with strings
const [step, wizard] = useWizard(['splash', 'name', 'email', 'terms', 'validation']); 

or

// For a nested wizard 
const [step, wizard] = useWizard(["A", "B", {
        "1": ["C", "D", "E"],
        "2": ["F", "G"]
    }, "H"]);

There you go, that's all.

Now you can just use a switch to display content according to steps and use methods stored in wizard to navigate.

Methods compatibility

	linear wizard (numbers)	linear wizard (strings)	nested wizard
history	✔	✔	✔
nextStep	✔	✔	✔
previousStep	✔	✔	✔
nPreviousSteps	✔	✔	✔
nForwardSteps	✔	✔	✔
forwardStep	✔	✔	✔
initialize	✔	✔	✔
goToStep	✔	✔	✔
jumpSteps	✔	❌	❌
stepIndex	❌	✔	❌
wizardLength	❌	✔	❌

Get started the simple way

In this ultra-basic lizard (linear-wizard) scenario, each step is a number. Look at figure 1.1 bellow to see what we will achieve. figure 1.1

declare it

const [step, wizard] = useWizard();

And just use it

• step gives you the current step
• wizard gives you a set of methods (see at the end to see a list of all methods):
  • nextStep() increments step by 1
  • goToStep(n) sets step to n
  • previousStep() got to previous step (even if you jumped)
  • forwardStep() return to where you where when you used previousStep()
  • initialStep() go back to step1
  • jumpSteps(n) allows you to literally jump n steps (positive or negative integer)
  • nPreviousSteps() gives you the length of the history stack
  • nForwardSteps() gives you the length of the forward stack

Get started the crazy way

Instead of numbers, we will now use names (strings) for our steps.

We will first study a lizard scenario. We will then study two non-linear wizards.

The linear wizard with strings

This scenario is very close to the one above, but each step of the wizard is now a string. Look at figure 2.1 bellow to see what we will achieve. figure 2.1

Declare your wizard with an array of strings like so:

const [step, wizard] = useWizard(["A", "B", "C"]);

• Each value is the name of your step.
• Each step name must be unique.
• The entry point will always be the first value of the array.
• All wizard methods described above work out of the box.

The non-linear wizard (1 sub-path deep)

useWizard allows you to create non-linear paths in a simple declarative way. Look at figure 2.2 bellow to see what we will achieve. figure 3.1

All we have to do is to declare the wizard like above, but we will use an object instead of a string when we have different possible paths.

• Declare parallel paths in an object, where paths' keys are "1", "2", "3" ...
• Each array must always start with a string.
• Each object (at index n) must follow a string (at index n-1), so you give user a choice.

The example of the figure 3.1 would be written like this:

const path = ["A", "B", {
        "1": ["C", "D", "E"],
        "2": ["F", "G"]
    }, "H"];

const [step, wizard] = useWizard(path);

Again, most methods described in the first example works out of the box (see table bellow).

Another non-linear wizard (2 sub-paths deep)

This example only takes complexity a step ahead to show you what you can achieve. I will just give you the figure 2.3 and the declarative wizard that goes with it. figure 4.1

The example of the figure 4.1 would be written like this:

const path = ["A", "B", {
        "1": ["C", "D", "E"],
        "2": ["F", {
            "1": ["G", "H"],
            "2": ["I", "J", "K"]
        }, "L"]
    }, "M"];

const [step, wizard] = useWizard(path);

The first step would be again the step "A", and you can use all methods from the wizard object like above.

How deep does it get ?

As deep as you need it to be, you can nest parallel paths as much as you need to

Under the hood

This hook relies on two stacks stored as states. One is the history-stack, used to store the actual path the user took. The other one is the popped-history-stack, so the user can go forward when he went backward (see examples).

This hook heavily relies on recursion to identify steps in a nested pattern.

Go further

useWizard "only" helps you to handle multi-paths wizards. If you need to handle data (let's say you are using big nested forms), I invite you to check use-formidable.

What's next ?

Do not hesitate to ask for features / PR / or join

• [x] Unit testing for all functions
• [x] Move the master branch to main
• [x] Write examples
• [ ] Add a minifier / linter / webpack ... list to be determined, not urgent
• [ ] Test it with react-native