intro.js-react

A small React wrapper around Intro.js. The wrapper provides support for both steps and hints.

Quicklinks

• Example
• Installation
• Usage
  • Steps
  • Hints
• Intro.js API
• Intro.js options

Example

You can find a small example here on codesandbox.io.

Installation

Install using Npm (don't forget to add the --save option if you're still using npm < 5):

$ npm install intro.js-react

Or Yarn:

$ yarn add intro.js-react

Make sure to have React & Intro.js installed (they're peer dependencies) and the Intro.js CSS definitions properly loaded into your project.

This would usually looks like:

import 'intro.js/introjs.css';

Usage

Two component are available for both steps and hints:

import { Steps, Hints } from 'intro.js-react';

Steps

Note: Steps indexes always starts from 0 in this wrapper instead of 1 like in Intro.js.

Basic example:

<Steps
  enabled={stepsEnabled}
  steps={steps}
  initialStep={initialStep}
  onExit={this.onExit}
/>

Props

| Name | Description | Type | Required | | --- | --- | :---: | :---: | | enabled | Defines if the steps are visible or not. Default: false. | Boolean | | | initialStep | Step index to start with when showing the steps. | Number | ✅ | | steps | All the steps. | Step[] | ✅ | | onExit | Callback called when the steps are disabled Required to force keeping track of the state when the steps are dismissed with an Intro.js event and not the enabled prop. | Function (stepIndex) | ✅ | | onStart | Callback called when the steps are enabled. | Function (stepIndex) | | | onChange | Callback called when the current step is changed. | Function (nextStepIndex, nextElement) | | | onBeforeChange | Callback called before changing the current step. If you want to prevent the transition to the next / previous step, you can return false in this callback (available since intro.js 2.8.0). | Function (nextStepIndex) | | | onAfterChange | Callback called after changing the current step. | Function (newStepIndex, newElement) | | | onPreventChange | Callback called if you prevented transitioning to a new step by returning false in onBeforeChange. | Function (stepIndex) | | | onComplete | Callback called when all the steps are completed. | Function () | | | options | Intro.js options. | Object | | |

Step

const steps = [
  {
    element: '.selector1',
    intro: 'test 1',
    position: 'right',
    tooltipClass: 'myTooltipClass',
    highlightClass: 'myHighlightClass',
  },
  {
    element: '.selector2',
    intro: 'test 2',
  },
  {
    element: '.selector3',
    intro: 'test 3',
  },
];

| Name | Description | Type | Required | | --- | --- | :---: | :---: | | element | CSS selector to use for the step. | String | | | intro | The tooltip text. | String | ✅ | | position | Position of the tooltip. | String | | | tooltipClass | CSS class of the tooltip. | String | | | highlightClass | CSS class of the helperLayer. | String | | |

Dynamic elements

If you want to use Intro.js Steps with dynamically created elements, you have to update the element associated to the step when it's available.

To do that, you can use the updateStepElement() API and pass to it the index of the step to update:

<Steps
  enabled={stepsEnabled}
  steps={steps}
  ref={steps => (this.steps = steps)}
/>

onBeforeChange = nextStepIndex => {
  if (nextStepIndex === 4) {
    this.steps.updateStepElement(nextStepIndex);
  }
}

Hints

Basic example:

<Hints
  enabled={hintsEnabled}
  hints={hints}
/>

Props

| Name | Description | Type | Required | | --- | --- | :---: | :---: | | enabled | Defines if the hints are visible or not. Default: false. | Boolean | | | hints | All the hints. | Hint[] | ✅ | | onClick | Callback called when a hint is clicked. | Function ( ) | | | onClose | Callback called when a hint is closed. | Function ( ) | | | options | Intro.js options. | Object | | |

Hint

const hints = [
  {
    element: '.selector1',
    hint: 'test 1',
    hintPosition: 'middle-middle',
  },
  {
    element: '.selector2',
    hint: 'test 2',
  },
];

| Name | Description | Type | Required | | --- | --- | :---: | :---: | | element | CSS selector to use for the hint. | String | ✅ | | hint | The tooltip text. | String | ✅ | | hintPosition | Position of the tooltip. | String | | |

Intro.js API

If for some reasons you need to use the Intro.js API, you can still get the Intro.js instance by using a ref on either the <Steps /> or <Hints /> components and using this.refName.introJs.

<Hints
  enabled={hintsEnabled}
  steps={hints}
  ref={hints => (this.hints = hints)}
/>

Intro.js options

You can find more details regarding Intro.js options and their default values in the documentation or directly in their code.

The wrapper overrides some Intro.js default options in the helpers/defaultProps.js file.

| Name | Description | Type | | --- | --- | :---: | | nextLabel | Next button label. | String | | prevLabel | Previous button label. | String | | skipLabel | Skip button label. | String | | doneLabel | Done button label. | String | | hidePrev | Hides the Previous button in the first step. | Boolean | | hideNextl | Hide the Next button in the last step. | Boolean | | tooltipPosition | Position of the tooltips. | String | | tooltipClass | CSS class of the tooltips. | String | | highlightClass | CSS class of the helperLayer. | String | | exitOnEsc | Exit by pressing Escape. | Boolean | | exitOnOverlayClick | Exit by clicking on the overlay layer. | Boolean | | showStepNumbers | Show steps number in a red circle. | Boolean | | keyboardNavigation | Allows navigation between steps using the keyboard. | Boolean | | showButtons | Show navigation buttons. | Boolean | | showBullets | Show bullets. | Boolean | | showProgress | Show progress indicator. | Boolean | | scrollToElement | Enables scrolling to hidden elements. | Boolean | | overlayOpacity | Opacity of the overlay. | Number | | scrollPadding | Padding when automatically scrolling to an element. | Number | | positionPrecedence | Precedence of positions. | String[] | | disableInteraction | Disables interaction inside elements. | Boolean | | hintPosition | Position of the hints. | String | | hintButtonLabel | Hint button label. | String | | hintAnimation | Enables hint animations. | Boolean |

License

Licensed under the MIT License, Copyright © HiDeoo.

See LICENSE for more information.