react-tour-guide

A lightweight, customizable onboarding tour library for React with light/dark/auto theme support.

Repository: github.com/yanesteves/react-tour-guide

Features

• 🎨 Light, Dark & Auto themes — follows system prefers-color-scheme
• 🎯 Smart positioning — auto-detects best tooltip placement
• ⌨️ Keyboard navigation — Arrow keys + Escape
• 💾 LocalStorage persistence — shows tour only on first visit
• 🔌 Hook API — useTour() for full programmatic control
• 📦 Zero dependencies — only React as peer dependency
• 🪶 Tiny bundle — ~4KB gzipped

Install

npm install react-tour-guide

Quick Start

import { TourProvider, useTour } from 'react-tour-guide';

const steps = [
  {
    id: 'welcome',
    title: 'Welcome! 👋',
    content: 'Let us show you around.',
  },
  {
    id: 'search',
    title: 'Search',
    content: 'Find anything here.',
    target: '[data-tour="search"]',
    placement: 'bottom',
  },
  {
    id: 'done',
    title: 'All Set! 🚀',
    content: 'You are ready to go!',
  },
];

function App() {
  return (
    <TourProvider steps={steps} storageKey="my-app-tour">
      <MyApp />
    </TourProvider>
  );
}

function MyApp() {
  const { start } = useTour();
  return (
    <div>
      <input data-tour="search" placeholder="Search..." />
      <button onClick={() => start()}>Replay Tour</button>
    </div>
  );
}

Color Modes

// Auto — follows OS preference (default)
<TourProvider steps={steps} colorMode="auto" />

// Always dark
<TourProvider steps={steps} colorMode="dark" />

// Always light
<TourProvider steps={steps} colorMode="light" />

Custom Theme

<TourProvider
  steps={steps}
  theme={{
    highlightColor: '#e11d48',
    primaryColor: '#e11d48',
    borderRadius: 16,
  }}
/>

Custom Labels (i18n)

<TourProvider
  steps={steps}
  labels={{
    next: 'Próximo',
    prev: 'Voltar',
    skip: 'Pular',
    finish: 'Começar!',
  }}
/>

useTour() Hook

const {
  isActive,     // boolean — tour is running
  currentStep,  // number — current step index
  step,         // TourStep | null — current step object
  totalSteps,   // number
  colorMode,    // 'light' | 'dark'
  start,        // (fromStep?: number) => void
  next,         // () => void
  prev,         // () => void
  goTo,         // (index: number) => void
  end,          // () => void
  reset,        // () => void — clears storage
} = useTour();

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | steps | TourStep[] | required | Array of tour steps | | storageKey | string | — | LocalStorage key for persistence | | colorMode | 'light' \| 'dark' \| 'auto' | 'auto' | Theme mode | | autoStart | boolean | true | Auto-start on mount | | theme | TourTheme | — | Custom theme overrides | | labels | object | English | Button label overrides | | keyboard | boolean | true | Enable keyboard nav | | closeOnOverlayClick | boolean | true | Click overlay to close | | showCloseButton | boolean | true | Show × button | | showDots | boolean | true | Show step indicators | | highlightPadding | number | 8 | Padding around target (px) | | tooltipOffset | number | 16 | Gap between tooltip and target (px) | | animationDuration | number | 300 | Animation duration (ms) | | zIndex | number | 10000 | Base z-index | | onComplete | () => void | — | Called when tour ends | | onStepChange | (index, step) => void | — | Called on step change |

License

MIT — yanesteves

Contributing

Contributions are welcome! Please open an issue or submit a pull request at github.com/yanesteves/react-tour-guide.