React Joyride: guided tours for React apps, from a single steps array

The onboarding problem React Joyride targets

A new user lands in a dashboard with twelve panels and no idea which three matter. Tooltips on hover do not help, because the user does not know where to hover. A modal with a screenshot goes stale the moment the layout changes. React Joyride exists for the middle ground: a sequence of small popovers, each pinned to a real element in the live DOM, advanced by a Next button, with the rest of the page dimmed.

The README frames it as showing your app to new users or explaining the functionality of new features. That second case is the more interesting one. Feature announcements inside an existing product are usually a single step pointed at a changed control, and the library handles that with the same steps array as a ten-step first-run tour. The audience is React application teams. The peer dependency range is react and react-dom 16.8 through 19, so this is not a framework-agnostic widget you drop into a Vue or Svelte page.

Steps, targets and the two APIs in v3

The unit of work is a step object. Each one carries a target, which the README shows as a CSS selector string like .my-first-step, and content, which is the text or node to render. The library resolves that selector against the document, positions a popover near the matched element, and moves to the next step when the user advances. Positioning is handled by @floating-ui/react-dom, which is listed in the package dependencies, and scrolling to off-screen targets is handled by the scroll and scrollparent packages. That is the data flow: you declare steps, the library owns placement, scrolling and the overlay.

Version 3 exposes two entry points. The component API renders a Joyride element with a run prop and a steps prop. The hook API, useJoyride, returns controls, state and a Tour node, so you can start the tour from your own button instead of on mount. The hook shape matters when the tour is user-triggered rather than automatic, which is common for a help menu item. The README also lists SSR safety as a highlight, naming Next.js and Remix, which means the overlay is not rendered during server rendering and the tour is expected to start client-side. The package sets sideEffects to false and ships ESM and CJS builds through the exports field, so tree shaking works with modern bundlers.

Installing React Joyride and running a first tour

The README gives one install command and no configuration step. Run it in your project root:

npm i react-joyride

Then declare your steps and render the component. The README's quick start uses a steps array with two entries and a Joyride element with run and steps. The target strings must match elements that are already in the DOM when the tour starts.

import { Joyride } from 'react-joyride';

const steps = [
  { target: '.my-first-step', content: 'This is my awesome feature!' },
  { target: '.my-other-step', content: 'This is another awesome feature!' },
];

export function App() {
  return (
    <div>
      <Joyride run steps={steps} />
      {/* your app */}
    </div>
  );
}

After that renders, you should see the first popover anchored to the element matching .my-first-step, with the rest of the page dimmed. If nothing appears, the usual cause is that the target selector matched nothing at the moment run became true.

If you want the tour behind a button rather than on mount, use the hook. The README's hook example returns Tour plus a start control:

import { useJoyride } from 'react-joyride';

export function App() {
  const { controls, state, Tour } = useJoyride({ steps });

  return (
    <div>
      <button onClick={() => controls.start()}>Start Tour</button>
      {Tour}
    </div>
  );
}

The repository also ships an agent skill, installed with npx skills add gilbarbara/react-joyride, which loads API and pattern knowledge into an AI assistant. That is a convenience for writing step definitions, not a runtime dependency.

Where React Joyride stops being the right tool

The target is a selector resolved against live DOM. That is the design's strength and its main failure mode. If your tour step points at a panel that only exists after a data fetch, or after the user opens a collapsed section, the selector matches nothing and the step has nothing to anchor to. The README does not document a retry or wait-for-target mechanism, so sequencing the tour behind your own loading state is on you. Teams that expect the library to wait for an element to appear will be disappointed.

Second, this is React-only by construction. The peer dependencies are react and react-dom, and both APIs are React components and hooks. If your application shell is not React, the library is not a candidate at all, regardless of how good the tour looks in the demo.

Third, the accessibility highlights are focus trapping, keyboard navigation and ARIA support, which cover the tour overlay itself. They do not make your step content accessible. A step whose content is a screenshot with text baked into the image is still inaccessible, and the library cannot fix that. The README does not claim otherwise, but the accessibility bullet is easy to over-read.

React Joyride compared with driver.js and Intro.js

The search data around this library is full of comparison queries, and the honest answer is that the three tools sit at different levels of coupling. React Joyride is a React component and hook. You pass it a steps array, it renders into your React tree, and it shares your React version constraints, which is why the peer range matters and why the v3 release notes call out React 16.8 through 19 support. Its custom components are React components and its styles are whatever you pass.

driver.js is framework-agnostic. It drives the DOM directly, so it works in a React page, a Vue page or plain HTML, and it does not care which React version you run. The cost is that you wire it up yourself with refs and effects, and you do not get a Tour node rendered as part of your component tree. Intro.js takes a similar DOM-first approach and has historically been the option people reach for when they want a tour in a non-React codebase.

If you are already in React and want the tour to behave like a component with props and state, React Joyride is the shorter path. If you need one tour implementation shared across a React app, a legacy jQuery admin page and a marketing site, the DOM-first tools avoid writing the integration three times.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-07-09. The most recent release is v3.2.0 on the same date, following v3.1.0 in April 2026 and v3.0.2 earlier that month. The release cadence in 2026 is real but not rapid: three releases across roughly three months, with the newest arriving alongside the last push.

The upgrade story is the part to plan for. The README points at a dedicated migration guide for moving from v2 to v3 rather than describing the changes inline, and the highlights claim the v3 bundle is about 30% smaller than v2. If you are on v2, treat the migration as a project with its own ticket, not a version bump. The dependency list is moderate for a UI library, with floating-ui, two @gilbarbara packages, is-lite, scroll, scrollparent, react-innertext and use-sync-external-store, so your lockfile will grow by that much.

The licence is MIT. That permits commercial use and modification, and it carries no copyleft obligation on your application code. This is a description of the licence text, not legal advice; if your organisation has a policy on third-party licences, route it through whoever owns that policy.

Editorial conclusion

Adopt React Joyride if your app is React 16.8 through 19, your tour targets are addressable by CSS selector, and you want the overlay, focus trapping and keyboard navigation handled for you. Do not adopt it if your product is not React, or if your tour has to run against markup that only exists after a server round trip and you cannot wait for that render. Verify first that your target selectors still resolve after your route transitions, and read the migration guide before moving an existing v2 tour, because the package documents a dedicated migration page rather than an in-place upgrade path.

Frequently asked questions

Official sources

1. gilbarbara/react-joyride on GitHub
2. License: MIT
3. Project website
4. README
5. Releases