Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/creativetimofficial/react-bootstrap-wizard


https://github.com/creativetimofficial/react-bootstrap-wizard

Last synced: 6 months ago
JSON representation

Awesome Lists containing this project

README 

          
# React Wizard



[![version][version-badge]][CHANGELOG] [![license][license-badge]][LICENSE]



**React Bootstrap Wizard** is a react component package that allows you to split a complicated flow or a complicated form in multiple steps and it's made with [reactstrap components](https://reactstrap.github.io/) and [React](https://reactjs.org/) using [Creative Tim Now UI styles](https://www.creative-tim.com/product/now-ui-kit-pro).



## Installation



```

npm install --save react-bootstrap-wizard@latest

```



## Usage



Import *react-wizard* in your component:

```

import ReactWizard from 'react-bootstrap-wizard';

```

After that, in your component render method add the following line:

```

 // where props are the properties you want

```



## Properties

```

ReactWizard.defaultProps = {

  validate: false,

  previousButtonText: "Previous",

  finishButtonText: "Finish",

  nextButtonText: "Next",

  color: "primary",

  progressbar: false

};



ReactWizard.propTypes = {

  color: PropTypes.oneOf(["primary", "green", "orange", "red", "blue"]),

  previousButtonClasses: PropTypes.string,

  finishButtonClasses: PropTypes.string,

  nextButtonClasses: PropTypes.string,

  headerTextCenter: PropTypes.bool,

  navSteps: PropTypes.bool,

  validate: PropTypes.bool,

  finishButtonClick: PropTypes.func,

  previousButtonText: PropTypes.node,

  finishButtonText: PropTypes.node,

  nextButtonText: PropTypes.node,

  title: PropTypes.node,

  description: PropTypes.node,

  progressbar: PropTypes.bool,

  steps: PropTypes.arrayOf(

    PropTypes.shape({

      stepName: PropTypes.string.isRequired,

      stepIcon: PropTypes.string,

      component: PropTypes.func.isRequired,

      stepProps: PropTypes.object,

    })

  ).isRequired

};

```



### *color*

This prop is used to create the background color of the header and can be one of (***default is the first option***):

```

1. 'primary'

2. 'green'

3. 'orange'

4. 'red'

5. 'blue'

```



### *previousButtonClasses*

This is a string prop that you can use it to add new classes to the previous button that appears in the footer.



### *nextButtonClasses*

This is a string prop that you can use it to add new classes to the next button that appears in the footer.



### *finishButtonClasses*

This is a string prop that you can use it to add new classes to the finish button that appears in the footer.



### *previousButtonText*

This is a prop used to add text/node to the previous button (default is ***Previous***).



### *nextButtonText*

This is a prop used to add text/node to the next button (default is ***Next***).



### *finishButtonText*

This is a prop used to add text/node to the previous button (default is ***Finish***).



### *headerTextCenter*

Use this prop to make the title and subtitle of the wizard center aligned.



### *navSteps*

Use this prop to make the wizard steps clickable.



### *title*

Use this prop to add a nice title to your wizard.



### *description*

Use this prop to add a nice description / subtitle to your wizard.



### *progressbar*

By setting this prop to true, a progressbar will we rendered instead of a moving tab for the active tab (default is ***false***).



### *steps*

This is an array of objects. This objects have two properties:

1. *stepName* -> used for the name that will appear in the nav (**these have to be unique**)

2. *stepIcon* -> used to add an icon alongside the name (**these has to be a string**)

3. *component* -> this is what will be rendered for each *stepName* (**has to be class/function**)

4. *stepProps* -> this props will be added to the step upon rendering (**has to be an object - like the state object**)

Example of steps:

```

var steps = [

  {

    stepName: "About",

    stepIcon: "tim-icons icon-single-02",

    component: Step1

  },

  {

    stepName: "Account",

    stepIcon: "tim-icons icon-settings-gear-63",

    component: Step2

  },

  {

    stepName: "Address",

    stepIcon: "tim-icons icon-delivery-fast",

    component: Step3,

    stepProps: {

      prop1: true,

      prop2: "A string"

    }

  }

];

```



### *validate*

This controls the validation of each step. The user won't be able to pass a step that isn't valid.

The validation is done in each step's component class/function.

You have to create a function **isValidated** with no parameters that will return one of *true* or *false*.

If returned *true*, than the user will be able to go to the next step, else if returned *false*, than the user won't be able to go to the next step.

If this prop is set, and the step component doesn't have the **isValidated** function, than the default will be considered **true**, and the user will be able to go to the next step.



### *finishButtonClick*

This function is called when the user presses the finish button.

See the bellow example to see how to use it.

```

function finishButtonClick(allStepStates)

```



## Example code with Class Components



```

import React from "react";

import ReactDOM from "react-dom";

import ReactWizard from "react-bootstrap-wizard";

import { Container, Row, Col } from "reactstrap";



import "bootstrap/dist/css/bootstrap.css";



class FirstStep extends React.Component {

  constructor(props) {

    super(props);

    this.state = {

      firstStep: "first step here"

    };

  }

  render() {

    return 
Hey from First
;

  }

}

class SecondStep extends React.Component {

  constructor(props) {

    super(props);

    this.state = {

      secondStep: "second step here"

    };

  }

  isValidated() {

    // do some validations

    // decide if you will

    return true;

    // or you will

    // return false;

  }

  render() {

    return 
Hey from Second
;

  }

}

class ThirdStep extends React.Component {

  constructor(props) {

    super(props);

    this.state = {

      thirdStep: "third step here"

    };

  }

  render() {

    return 
Hey from Third
;

  }

}



var steps = [

  // this step hasn't got a isValidated() function, so it will be considered to be true

  { stepName: "First", component: FirstStep },

  // this step will be validated to false

  { stepName: "Second", component: SecondStep },

  // this step will never be reachable because of the seconds isValidated() steps function that will always return false

  { stepName: "Third", component: ThirdStep }

];



class WizardExample extends React.Component {

  finishButtonClick(allStates) {

    console.log(allStates);

  }

  render() {

    return (

      

        

          

            

          

        

      

    );

  }

}



ReactDOM.render(, document.getElementById("root"));

```



## Example code with Function Components



### React.forwardRef



Note, since this plugin relays on its children (the steps that you pass to it), to have a ref, so that it can access the `isValidated` function, you will need to make sure you forward a ref, thus, you will need the `React.forwardRef`.



Check the bellow example to understand the issue better.



### React.useImperativeHandle



Note, since this plugin relays on its children (the steps that you pass to it), to have a ref, so that it can access the `isValidated` function, you will need to make sure that the wizard component will be able to access `this.refs.stepName.isValidated` (this is just an example), and that is why, we will need to use the `React.useImperativeHandle` to add a function here, named `isValidated` which will further call the `isValidated` function of the component, or we will set it to undefined. We also use it for retrieving the state of the component.



Check the bellow example to understand the issue better.



### isValidated inside React.useImperativeHandle



We use this function, to let the parent component, the wizard, access the `isValidated` prop/function of its children.



Check the bellow example to understand the issue better.



### state inside React.useImperativeHandle



We use this property, to let the parent component, the wizard, access the `state` of its children.



Check the bellow example to understand the issue better.



### Example



```

import React from "react";

import ReactDOM from "react-dom";

import ReactWizard from "react-bootstrap-wizard";

import { Container, Row, Col } from "reactstrap";



import "bootstrap/dist/css/bootstrap.css";



const FirstStep = React.forwardRef((props, ref) => {

  const [randomState, setRandomState] = React.useState(

    "1. This is a random state for first step."

  );

  React.useImperativeHandle(ref, () => ({

    isValidated: undefined,

    state: {

      randomState,

    },

  }));

  return 
Hey from First
;

});



const SecondStep = React.forwardRef((props, ref) => {

  const [randomState, setRandomState] = React.useState(

    "2. This is a random state for second step."

  );

  const isValidated = () => {

    // do some validations

    // decide if you will

    return true;

    // or you will

    // return false;

  };

  React.useImperativeHandle(ref, () => ({

    isValidated: () => {

      return isValidated();

    },

    state: {

      randomState,

    },

  }));

  return 
Hey from Second
;

});



const ThirdStep = React.forwardRef((props, ref) => {

  const [randomState, setRandomState] = React.useState(

    "3. This is a random state for third step."

  );

  React.useImperativeHandle(ref, () => ({

    isValidated: undefined,

    state: {

      randomState,

    },

  }));

  return 
Hey from Third
;

});



var steps = [

  // this step hasn't got a isValidated() function, so it will be considered to be true

  { stepName: "First", component: FirstStep },

  // this step will be validated to false

  { stepName: "Second", component: SecondStep },

  // this step will never be reachable because of the seconds isValidated() steps function that will always return false

  { stepName: "Third", component: ThirdStep },

];



function WizardExample() {

  const finishButtonClick = (allStates) => {

    console.log(allStates);

  };

  return (

    

      

        

          

        

      

    

  );

}



ReactDOM.render(, document.getElementById("root"));



```



## How to work with NextJS



You will need to change:

```

import ReactWizard from "react-bootstrap-wizard";

```

To:

```

import dynamic from 'next/dynamic'



const ReactWizard = dynamic(() => import('react-bootstrap-wizard'))



if (typeof window === "undefined") {

  global.window = {};

}

if (typeof document === "undefined") {

  global.document = {};

}

```



## Styles

Be sure to include the styles in your project.

You can either include the css:

```

import "react-bootstrap-wizard/dist/react-wizard.css"

```

Or the scss

```

import "react-bootstrap-wizard/dist/react-wizard.scss"

```



## Dependencies



For this component to work properly you need to have the following libraries installed in your project:



```

npm install --save reactstrap

npm install --save bootstrap

```



[CHANGELOG]: ./CHANGELOG.md



[LICENSE]: ./LICENSE.md

[version-badge]: https://img.shields.io/badge/version-0.0.9-blue.svg

[license-badge]: https://img.shields.io/badge/license-MIT-blue.svg