Introduction

Choose visual authoring, portable documents, or the React API to build your first guide.

Tourlight includes a React player, a visual Studio, and portable documents that your teammates and agents can edit. Use the player directly, or start with the Studio playground.

Studio, portable documents, guidance components, and the CLI require react-tourlight 0.5.0 or later. You can also run the demo from source:

pnpm install
pnpm build
pnpm --filter react-tourlight-docs dev

Run these from the repository root, then visit /studio on the local URL.

Installation

Install react-tourlight and its peer dependency:

npm install react-tourlight@^0.5.0 @floating-ui/react-dom

@floating-ui/react-dom is used for intelligent tooltip positioning (flip, shift, overflow handling). It's listed as a peer dependency to keep the core bundle small.

Import the stylesheet

react-tourlight ships a small CSS file for the overlay and transitions. Import it once at the root of your app:

import 'react-tourlight/styles.css'

Wrap your app in SpotlightProvider

SpotlightProvider manages all tour and highlight state. Place it near the root of your component tree:

import { SpotlightProvider } from 'react-tourlight'
import 'react-tourlight/styles.css'

export default function App() {
  return (
    <SpotlightProvider>
      <YourApp />
    </SpotlightProvider>
  )
}

Define your tour steps

Each step targets a DOM element (via CSS selector or React ref), and includes a title, content, and optional placement:

import { SpotlightTour } from 'react-tourlight'

const steps = [
  {
    target: '#search-input',
    title: 'Search',
    content: 'Find anything instantly with our search.',
    placement: 'bottom' as const,
  },
  {
    target: '[data-tour="sidebar"]',
    title: 'Navigation',
    content: 'Browse your projects and teams here.',
    placement: 'right' as const,
  },
  {
    target: '#create-button',
    title: 'Create',
    content: 'Start a new project in one click.',
    placement: 'bottom' as const,
  },
]

// SpotlightTour registers the steps — it doesn't render any UI itself.
<SpotlightTour id="onboarding" steps={steps} />

Start the tour

Use the useSpotlight hook to start, stop, or control any registered tour:

import { useSpotlight } from 'react-tourlight'

function OnboardingButton() {
  const { start } = useSpotlight()

  return (
    <button onClick={() => start('onboarding')}>
      Start Tour
    </button>
  )
}

Full working example

Putting it all together:

import { SpotlightProvider, SpotlightTour, useSpotlight } from 'react-tourlight'
import 'react-tourlight/styles.css'

function App() {
  return (
    <SpotlightProvider>
      <SpotlightTour
        id="onboarding"
        steps={[
          {
            target: '#search-input',
            title: 'Search',
            content: 'Find anything instantly with our search.',
            placement: 'bottom',
          },
          {
            target: '[data-tour="sidebar"]',
            title: 'Navigation',
            content: 'Browse your projects and teams here.',
            placement: 'right',
          },
          {
            target: '#create-button',
            title: 'Create',
            content: 'Start a new project in one click.',
            placement: 'bottom',
          },
        ]}
        onComplete={() => console.log('Tour complete!')}
      />
      <Dashboard />
    </SpotlightProvider>
  )
}

function Dashboard() {
  const { start } = useSpotlight()

  return (
    <div>
      <header>
        <input id="search-input" placeholder="Search..." />
        <button id="create-button">New Project</button>
      </header>
      <nav data-tour="sidebar">
        {/* sidebar content */}
      </nav>
      <main>
        <button onClick={() => start('onboarding')}>
          Start Tour
        </button>
      </main>
    </div>
  )
}

Next steps

Visual Studio -- author guides in your integrated app
Tour Documents -- a shared JSON artifact for your team
Build with Agents -- skill, CLI, and MCP setup
Testing & Diagnostics -- check targets and real journeys
Multi-Step Tours -- step configuration, lifecycle hooks, and conditional steps
Single-Element Highlights -- one-off "what's new" callouts
Customization -- themes, custom tooltips, and i18n
API Reference -- full props and types reference