react-guided-journey

A complete, headless React onboarding system — not just a tooltip library.

▶ Live interactive demo · Getting started · Hosting · Publishing · Sponsor

Try every feature live before you install — tours, checklist, help center, discovery tips, theming, and the persisted state (refresh to see it resume).

Ships with guided tours (spotlight + tooltips), a getting-started checklist with progress tracking, dismissible discovery banners, a help center drawer, and a welcome modal — all driven by one minimal, DB-ready state shape.

• Zero runtime dependencies. Only React as a peer dep. The store is a tiny useSyncExternalStore implementation, no zustand/redux.
• Router-agnostic. You pass currentPath and onNavigate — works with react-router, TanStack Router, Next.js, anything.
• Role-agnostic. Roles are plain strings; no coupling to an auth library.
• DB-ready persistence. The persisted state is four id-arrays that map cleanly to a single row. Default localStorage adapter; bring your own async adapter for a backend.

Why this over react-joyride / driver.js / Shepherd?

| | react-guided-journey | react-joyride | driver.js | Shepherd | |---|---|---|---|---| | Runtime deps | 0 | several | 0 | several | | Checklist + progress | ✅ built-in | ❌ | ❌ | ❌ | | Persistence (resume) | ✅ pluggable | ❌ | ❌ | ❌ | | Help center / welcome | ✅ | ❌ | ❌ | ❌ | | Navigate-then-tour | ✅ | ❌ | ❌ | ❌ | | Role-aware tours | ✅ | ❌ | ❌ | ❌ | | Tooltip placement | measure-then-show | static estimate | static | popper | | Async target waiting | ✅ MutationObserver | partial | ❌ | ❌ | | Keyboard nav + a11y | ✅ | ✅ | partial | ✅ | | Tooltip arrow/caret | ✅ | ✅ | ✅ | ✅ |

A modern alternative to react-joyride, driver.js, Shepherd.js, intro.js & Reactour

If you're comparing React onboarding / product-tour libraries, here's where react-guided-journey fits:

• vs react-joyride — joyride is tours-only and unmaintained-ish; this adds a checklist, help center, discovery tips and persistence, with zero runtime deps.
• vs driver.js — driver.js is a great vanilla-JS highlighter but not React-native and has no checklist or resume-state; this is built for React with a full onboarding model.
• vs Shepherd.js / intro.js — both are tour engines; this is a complete onboarding system (tour + checklist
  • help center + tips) in one headless, themeable package.
• vs Reactour / Onborda / NextStep — similar tour scope; this adds progress tracking, DB-ready persistence, role-aware content and a navigate-then-tour flow.

Short version: most of these are tooltip/tour libraries. This is an onboarding system — tours and a progress checklist and a help center and discovery tips, sharing one DB-ready state shape.

Install

npm install react-guided-journey

import { OnboardingProvider } from "react-guided-journey";
import "react-guided-journey/styles.css";

Quick start

One provider, near the root, inside your router. The nesting is always Router → OnboardingProvider → App. Here's a complete main.tsx:

// src/main.tsx
import { createRoot } from "react-dom/client";
import { BrowserRouter, useLocation, useNavigate } from "react-router-dom";
import { OnboardingProvider } from "react-guided-journey";
import "react-guided-journey/styles.css";
import App from "./App";
import { tours, journeys } from "./onboarding/config";

function AppProviders({ children }: { children: React.ReactNode }) {
  const { pathname } = useLocation();   // must be inside the router
  const navigate = useNavigate();
  return (
    <OnboardingProvider
      config={{ tours, journeys, currentPath: pathname, onNavigate: navigate }}
    >
      {children}
    </OnboardingProvider>
  );
}

createRoot(document.getElementById("root")!).render(
  <BrowserRouter>
    <AppProviders>
      <App />
    </AppProviders>
  </BrowserRouter>,
);

That's the whole setup — the welcome modal, checklist, help center and tours now render automatically. See the Getting started guide for roles, persistence, theming and more, or run the interactive demo locally:

cd demo
npm install
npm run dev   # http://localhost:5173

Concepts

• Tour — an ordered list of spotlighted steps tied to a route. Set autoLaunch: true to start it the first time a user reaches its route.
• Step — { id, target (CSS selector), title, content, placement }. Each step can set its own width, spotlightPadding, async onBeforeStep (e.g. open a menu / await a fetch before highlighting) and onAfterStep.
• Journey — a role-specific checklist of tasks + an optional welcome modal. A task with a tourId shows a "Show me how" button; finishing that tour completes the task automatically (matched by the task's id). Tasks render in array order and can carry an icon (any React node — a component or emoji).
• Discovery — a small dismissible "tip" banner. Floating (corner) tips render automatically from config; inline tips are placed with <DiscoveryBanner id="…" /> where you want them. Stays dismissed once closed.

How a checklist task links to a tour

You declare the link in one place — the task's tourId:

// journey
steps: [
  { id: "take-tour", title: "Take the product tour", icon: "🗺️", tourId: "product-tour" },
]

// tour
{ id: "product-tour", route: "/", title: "Product tour", steps: [/* … */] }

• Finishing product-tour completes the take-tour task — no checklistStepId needed (it's auto-derived from tourId; set it only to override).
• The task's "Go" button defaults to the tour's route, so you don't repeat route on the task. Set the task's own route only for a task with no tour.
• order is optional — tasks render in array order; set it only to override.

Persisted state (DB-ready)

interface PersistedState {
  welcomeSeen: boolean;
  completedSteps: string[];        // finished checklist tasks
  seenTours: string[];             // completed OR dismissed — gates auto-launch
  dismissedDiscoveries: string[];
}

Use a custom backend instead of localStorage:

const adapter: PersistenceAdapter = {
  load: () => fetch(`/api/onboarding/${userId}`).then((r) => r.json()),
  save: (state) =>
    fetch(`/api/onboarding/${userId}`, {
      method: "PUT",
      body: JSON.stringify(state),
    }),
};

<OnboardingProvider config={{ ...config, persistence: adapter }}>

Lifecycle callbacks

callbacks: {
  onTourStart, onTourComplete, onTourSkip,
  onStepChange, onStepComplete, onChecklistComplete,
}

Theming

Override any CSS variable (--rgj-primary, --rgj-surface, --rgj-radius, …) in your own stylesheet. Or set renderDefaultUI={false} on the provider and build your own UI with the exported useOnboarding() hook + <TourRenderer />.

Sponsor

react-guided-journey is free and MIT-licensed. If it saves you time, you can support its development via GitHub Sponsors — one-time or monthly. Thank you 🙏

License

MIT © Alpesh Baraiya