react-spotlight-tour

A zero-config, role-based interactive product tour library for React.
Build guided tours visually with a dev toolbar, spotlight overlays, and smart tooltips. No CSS imports needed.

Features

• 🎯 Visual Element Picker — Click any DOM element to add a tour step
• 🌑 Spotlight Overlay — Dark backdrop with animated cutout on target element
• 💬 Smart Tooltips — Auto-positioned (top/bottom/left/right) with progress bar & dot indicators
• 👥 Role-Based Filtering — Show tours only to specific user roles
• 🔒 Super-User Dev Mode — Restrict tour building to privileged users only
• 📦 Zero CSS Imports — Styles injected automatically at runtime
• 💾 localStorage Persistence — Flows survive page reloads
• ↕ Drag-and-Drop — Reorder steps visually in the toolbar
• 📤 Export / Import — Save and restore flow configurations as JSON

Installation

npm install react-spotlight-tour

Quick Start

Wrap your root component with SpotlightProvider. Place it inside your Redux/Context providers so it has access to user data:

import { SpotlightProvider } from 'react-spotlight-tour';

function App() {
  const userRole = useSelector(state => state.userManagement.userData.role);

  return (
    <SpotlightProvider
      devMode={userRole === 'Super User'}   // Only Super Users can build tours
      currentRole={userRole || 'user'}
      primaryColor="#6366f1"
      initialFlows={[]}
    >
      {/* Your entire application */}
    </SpotlightProvider>
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | devMode | boolean | false | Shows the dev toolbar. Set to true only for privileged users. | | currentRole | string | 'user' | The current user's role. Used to filter visible tours. | | primaryColor | string | '#6366f1' | Accent color for the spotlight UI. | | initialFlows | array | [] | Pre-seeded flows (localStorage takes priority). |

How It Works

For Developers (devMode = true)

1. The Spotlight Builder panel appears docked to the right side of the page.
2. Click New Flow → enter a name → select which roles can see it.
3. Select the flow → click Pick Element → click any element on the page.
4. Fill in the step title and description in the modal → click Add Step.
5. Repeat to add more steps. Drag to reorder.
6. Click ▶ Preview to see the tour as an end user would.
7. Use Settings → Export to back up your flows as JSON.

For End Users (devMode = false)

• A floating 🎯 button appears in the bottom-right corner if tours are available for their role.
• Clicking it starts the tour (or shows a chooser if multiple tours exist).
• Navigate with Prev / Next / Done buttons, or press Esc to exit.

Role-Based Filtering

Each flow has a roles array. The TourLauncher shows only flows where currentRole is in the list.

{
  "name": "Admin Onboarding",
  "roles": ["Super User", "IT Admin"],
  "steps": [...]
}

Use "*" as a wildcard to show a flow to all roles:

{ "roles": ["*"] }

useSpotlight Hook

Access the full tour context from any component inside SpotlightProvider:

import { useSpotlight } from 'react-spotlight-tour';

function MyComponent() {
  const { flows, startTour, endTour, currentRole } = useSpotlight();
  // ...
}

Export / Import

In the dev toolbar Settings tab:

• Export Flows JSON — Downloads the current flows as a .json file.
• Import Flows JSON — Uploads a previously exported file, overwriting current flows.

License

MIT