react-onboard-kit 🧩

Zero-dependency React library for beautiful product tours, spotlight walkthroughs, and onboarding experiences.

Zero-dependency React library for product tours and onboarding walkthroughs

▶ Try the live demo

Features

• 🎯 Spotlight — focuses user attention with an overlay cutout
• 💬 Tooltip — positioned callout with title, body, and navigation
• 🎨 Fully customizable — style every pixel via theme props
• ⌨️ Keyboard navigation — arrow keys + Escape
• ♿ Accessible — focus management, aria labels
• 📦 Zero dependencies — only React as a peer dep
• 🔷 TypeScript — fully typed

Installation

npm install react-onboard-kit

Quick Start

import { TourProvider, TourStep, TourOverlay, useTour } from "react-onboard-kit";

function App() {
  return (
    <TourProvider>
      <MyPage />
      <TourOverlay />
    </TourProvider>
  );
}

function MyPage() {
  const { start } = useTour();

  return (
    <div>
      <TourStep id="step-1" title="Welcome!" content="This is your dashboard.">
        <div className="dashboard-header">Dashboard</div>
      </TourStep>

      <TourStep id="step-2" title="Analytics" content="Track your key metrics here." placement="right">
        <div className="analytics-panel">Analytics</div>
      </TourStep>

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

API

<TourProvider>

Wrap your app with TourProvider. Accepts an optional theme prop.

| Prop | Type | Description | |------|------|-------------| | theme | TourTheme | Style overrides (see below) | | onStart | () => void | Called when tour starts | | onEnd | () => void | Called when tour ends | | onStepChange | (index, step) => void | Called on each step change |

<TourStep>

Wraps any element and registers it as a tour stop.

| Prop | Type | Default | Description | |------|------|---------|-------------| | id | string | required | Unique step identifier | | title | string | — | Tooltip title | | content | string | required | Tooltip body text | | placement | "top" \| "bottom" \| "left" \| "right" | "bottom" | Tooltip position |

<TourOverlay>

Renders the spotlight and tooltip. Place this once near the root of your app.

useTour()

Hook to control the tour programmatically.

| Method | Description | |--------|-------------| | start(stepIds?) | Start the tour (optionally with specific step IDs in order) | | stop() | Stop the tour | | next() | Go to next step | | prev() | Go to previous step | | goTo(index) | Jump to a specific step | | active | Whether the tour is active | | currentIndex | Current step index | | steps | Array of registered steps |

TourTheme

Pass any of these to <TourProvider theme={...}>:

interface TourTheme {
  overlayColor?: string;           // default: "rgba(0,0,0,0.6)"
  tooltipBackground?: string;      // default: "#ffffff"
  tooltipColor?: string;           // default: "#111111"
  tooltipBorder?: string;          // default: "1px solid #e5e7eb"
  tooltipBorderRadius?: string;    // default: "12px"
  buttonBackground?: string;       // default: "#6366f1"
  buttonColor?: string;            // default: "#ffffff"
  buttonBorderRadius?: string;     // default: "8px"
  spotlightBorderRadius?: string;  // default: "8px"
  spotlightPadding?: number;       // default: 8 (px)
  zIndex?: number;                 // default: 9999
}

Keyboard Support

| Key | Action | |-----|--------| | → | Next step | | ← | Previous step | | Esc | Close tour |

License

MIT