{"id":11093,"library":"intro.js-react","title":"Intro.js React Wrapper","description":"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.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/HiDeoo/intro.js-react","tags":["javascript","intro.js","react","wrapper","typescript"],"install":[{"cmd":"npm install intro.js-react","lang":"bash","label":"npm"},{"cmd":"yarn add intro.js-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add intro.js-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core tour functionality. Required as a peer dependency.","package":"intro.js","optional":false},{"reason":"Required for building React components. Required as a peer dependency.","package":"react","optional":false}],"imports":[{"note":"Main component for creating step-by-step product tours.","wrong":"const Steps = require('intro.js-react').Steps;","symbol":"Steps","correct":"import { Steps } from 'intro.js-react';"},{"note":"Component for displaying contextual hints. Both Steps and Hints are named exports.","wrong":"import Hints from 'intro.js-react/Hints';","symbol":"Hints","correct":"import { Hints } from 'intro.js-react';"},{"note":"The styling for Intro.js must be imported directly from the `intro.js` package, not this wrapper.","wrong":"import 'intro.js-react/dist/introjs.css';","symbol":"intro.js/introjs.css","correct":"import 'intro.js/introjs.css';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport { Steps } from 'intro.js-react';\nimport 'intro.js/introjs.css'; // Don't forget to import Intro.js CSS\n\n// Simulate some elements for the tour\nconst MyComponent = () => {\n const [stepsEnabled, setStepsEnabled] = useState(true);\n const [initialStep, setInitialStep] = useState(0);\n\n const steps = [\n {\n element: '.step-one-selector', // Make sure this selector exists in your DOM\n intro: 'This is the first step of our tour!',\n position: 'right',\n },\n {\n element: '.step-two-selector',\n intro: 'And here is the second important element.',\n },\n {\n element: '.step-three-selector',\n intro: 'Finally, this is the last piece of information.',\n position: 'bottom',\n },\n ];\n\n const onExit = () => {\n setStepsEnabled(false);\n setInitialStep(0); // Reset for next time\n };\n\n return (\n
\n

Welcome to My App

\n

This is some content.

\n \n\n \n
\n );\n};\n\nexport default MyComponent;","lang":"typescript","description":"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."},"warnings":[{"fix":"Run `npm install intro.js react` or `yarn add intro.js react`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `import 'intro.js/introjs.css';` to your application's entry point or a relevant component file.","message":"The `intro.js` CSS styles must be manually imported into your project. This wrapper does not automatically include them.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Adjust your step indexing to start from 0 when working with `intro.js-react` components and callbacks.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always provide an `onExit` function to the `Steps` component that sets `enabled` to `false` and resets `initialStep` if desired.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `intro.js` is installed and add `import 'intro.js/introjs.css';` to your project.","cause":"The Intro.js CSS file is missing or the import path is incorrect.","error":"Module not found: Can't resolve 'intro.js/introjs.css'"},{"fix":"Install the peer dependencies: `npm install intro.js react` or `yarn add intro.js react`.","cause":"The peer dependencies `intro.js` or `react` have not been installed.","error":"Error: Cannot find module 'intro.js' or 'react'"},{"fix":"Define and pass an `onExit` function to the `Steps` component, typically to set `enabled` to `false`.","cause":"The `onExit` callback prop was not provided to the `Steps` component.","error":"The prop `onExit` is marked as required in `Steps`, but its value is `undefined`."}],"ecosystem":"npm"}