search

HiDeoo / intro.js-react

Intro.js react wrapper
MIT License
409 stars 57 forks source link
introjs react

readme

intro.js-react

integration Coverage Status

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

Quicklinks

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)		 ✅
onBeforeExit Callback called before exiting the intro.
If you want to prevent exiting the intro, you can return false in this callback (available since intro.js 0.2.7).		 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, nextElement)
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 content. String | React element ✅
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}
  hints={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
hideNext 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.