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.