Intro.js React Wrapper

1.0.0 · active · verified Sun Apr 19

intro.js-react is a lightweight and actively maintained React wrapper for the Intro.js library, designed to simplify the creation of step-by-step product tours and hints within React applications. Currently at version 1.0.0, this package provides two primary components: `Steps` for guided tours and `Hints` for contextual popovers. It abstracts away direct Intro.js imperative API calls, allowing developers to manage tours declaratively using React props for configuration, steps, and lifecycle callbacks. Key differentiators include its adherence to React's component model, handling Intro.js instance management, and providing a more idiomatic React experience compared to integrating Intro.js directly. While it requires `intro.js` and `react` as peer dependencies, it handles the synchronization between React state and the underlying Intro.js instance, offering callbacks for various tour events like `onStart`, `onChange`, and `onComplete`. The package also supports Intro.js options directly through a dedicated `options` prop.

Common errors

```
Module not found: Can't resolve 'intro.js/introjs.css'
```
cause The Intro.js CSS file is missing or the import path is incorrect.

fix Ensure `intro.js` is installed and add `import 'intro.js/introjs.css';` to your project.
```
Error: Cannot find module 'intro.js' or 'react'
```
cause The peer dependencies `intro.js` or `react` have not been installed.

fix Install the peer dependencies: `npm install intro.js react` or `yarn add intro.js react`.
```
The prop `onExit` is marked as required in `Steps`, but its value is `undefined`.
```
cause The `onExit` callback prop was not provided to the `Steps` component.

fix Define and pass an `onExit` function to the `Steps` component, typically to set `enabled` to `false`.

Warnings

gotcha Both `intro.js` and `react` are peer dependencies and must be installed separately alongside `intro.js-react`. Failure to do so will result in runtime errors.
Fix: Run `npm install intro.js react` or `yarn add intro.js react`.
gotcha The `intro.js` CSS styles must be manually imported into your project. This wrapper does not automatically include them.
Fix: Add `import 'intro.js/introjs.css';` to your application's entry point or a relevant component file.
gotcha Step indexes in `intro.js-react` (e.g., for `initialStep` and `onExit` callbacks) are 0-based, unlike the underlying `intro.js` library where they are 1-based. Be mindful of this difference when migrating or debugging.
Fix: Adjust your step indexing to start from 0 when working with `intro.js-react` components and callbacks.
gotcha The `onExit` prop for the `Steps` component is required. This callback is crucial for updating your component's state when the Intro.js tour is dismissed by user action (e.g., pressing ESC or clicking 'Done'), ensuring the `enabled` prop remains synchronized.
Fix: Always provide an `onExit` function to the `Steps` component that sets `enabled` to `false` and resets `initialStep` if desired.

Install

npm install intro.js-react npm
yarn add intro.js-react yarn
pnpm add intro.js-react pnpm

Imports

Steps

wrong:

const Steps = require('intro.js-react').Steps;

correct:

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

Main component for creating step-by-step product tours.

Hints
wrong:
```
import Hints from 'intro.js-react/Hints';
```
correct:
```
import { Hints } from 'intro.js-react';
```
Component for displaying contextual hints. Both Steps and Hints are named exports.
intro.js/introjs.css
wrong:
```
import 'intro.js-react/dist/introjs.css';
```
correct:
```
import 'intro.js/introjs.css';
```
The styling for Intro.js must be imported directly from the `intro.js` package, not this wrapper.

Quickstart

Demonstrates how to integrate `intro.js-react` to create a guided product tour using the `Steps` component, including state management for enabling/disabling the tour and defining tour steps with CSS selectors.

import React, { useState } from 'react';
import { Steps } from 'intro.js-react';
import 'intro.js/introjs.css'; // Don't forget to import Intro.js CSS

// Simulate some elements for the tour
const MyComponent = () => {
  const [stepsEnabled, setStepsEnabled] = useState(true);
  const [initialStep, setInitialStep] = useState(0);

  const steps = [
    {
      element: '.step-one-selector', // Make sure this selector exists in your DOM
      intro: 'This is the first step of our tour!',
      position: 'right',
    },
    {
      element: '.step-two-selector',
      intro: 'And here is the second important element.',
    },
    {
      element: '.step-three-selector',
      intro: 'Finally, this is the last piece of information.',
      position: 'bottom',
    },
  ];

  const onExit = () => {
    setStepsEnabled(false);
    setInitialStep(0); // Reset for next time
  };

  return (
    <div>
      <h1 className="step-one-selector">Welcome to My App</h1>
      <p className="step-two-selector">This is some content.</p>
      <button className="step-three-selector" onClick={() => setStepsEnabled(true)}>
        Start Tour
      </button>

      <Steps
        enabled={stepsEnabled}
        steps={steps}
        initialStep={initialStep}
        onExit={onExit}
        // You can also pass Intro.js options directly
        options={{
          showButtons: true,
          showStepNumbers: false,
          exitOnOverlayClick: false,
        }}
      />
    </div>
  );
};

export default MyComponent;

view raw JSON →