react-voyage

Liquid-smooth guided tours for React

The guided tour library your users deserve — Award-winning onboarding UX in one component

View on GitHub • Live Demo

🚀 Install

npm install react-voyage
# or
pnpm add react-voyage
# or
yarn add react-voyage

Peer dependencies (install separately):

npm install react react-dom framer-motion

⚡ Quick Start

Get a working tour in under 30 seconds:

import { Voyage } from 'react-voyage';
import 'react-voyage/style.css';

function App() {
  const [active, setActive] = useState(false);

  const steps = [
    {
      target: '#feature-1',
      title: 'Welcome!',
      content: 'This is your first feature.',
    },
    {
      target: '#feature-2',
      title: 'Another Feature',
      content: 'Here is another important feature.',
    },
  ];

  return (
    <>
      <button onClick={() => setActive(true)}>Start Tour</button>
      <Voyage 
        steps={steps} 
        active={active} 
        onEnd={() => setActive(false)} 
      />
    </>
  );
}

That's it! Your tour is ready. 🎉

✨ Why react-voyage?

| Feature | Description | |---------|-------------| | ✨ Beautiful by default | Glassmorphism UI, liquid spotlight, micro-animations that feel premium | | ⚡ Zero config | One component, one prop. Works in 30 seconds. No setup required. | | 🎨 Deeply customizable | Theming, render overrides, full control when you need it | | ♿ Accessible | Keyboard nav, focus trap, screen reader support, WCAG compliant |

🎯 Features

💧 Liquid Spotlight Effect

SVG mask morphing with Framer Motion spring physics. The spotlight smoothly transitions between targets with a "liquid" feel that's impossible to ignore.

🎨 Glassmorphism UI

Premium frosted glass tooltips with backdrop-blur-xl, subtle borders, and elegant shadows. Looks stunning in both light and dark modes.

⚡ Zero-Config DX

Drop-in usage with sensible defaults. No configuration files, no setup steps. Just import and use.

🎛️ Deep Customization

• Custom tooltip rendering
• Custom controls
• Custom spotlight effects
• Full theme control
• Render props for everything

♿ Built-in Accessibility

• Full ARIA support
• Keyboard navigation (Escape, Enter, Arrow keys)
• Focus management
• Screen reader announcements
• Respects prefers-reduced-motion
• High contrast mode support

📱 Responsive & SSR-Safe

• Auto-positioning tooltips with Floating UI
• ResizeObserver for dynamic updates
• Works with Next.js, Remix, and all SSR frameworks
• No hydration mismatches

📖 API Reference

<Voyage /> Component

| Prop | Type | Default | Description | |------|------|---------|-------------| | steps | Step[] | required | Array of tour steps | | active | boolean | false | Whether the tour is active | | initialStep | number | 0 | Initial step index | | onStart | () => void | - | Callback when tour starts | | onEnd | (completed: boolean) => void | - | Callback when tour ends | | onStepChange | (step: number, direction: 'next' \| 'prev') => void | - | Callback when step changes | | onSkip | (stepIndex: number) => void | - | Callback when tour is skipped | | interactionMode | 'block-all' \| 'allow-target' \| 'allow-all' | 'block-all' | Overlay click behavior | | overlayOpacity | number | 0.75 | Overlay opacity (0-1) | | overlayColor | string | '#000000' | Overlay background color | | maskPadding | number | 8 | Padding around spotlight cutout (px) (deprecated, use spotlightPadding) | | spotlightPadding | number \| { x: number, y: number } | 8 | Breathing room around target element. Can be uniform or per-axis. | | borderRadius | number | 8 | Border radius for spotlight (px) | | spotlightShadow | string | '0 0 40px rgba(255, 255, 255, 0.1)' | Spotlight shadow/blur CSS | | spotlightTransitionDuration | number | 1000 | Spotlight morphing duration in milliseconds | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | Theme mode | | showProgress | boolean | true | Show progress bar indicating current step | | showKeyboardShortcuts | boolean | true | Show keyboard shortcuts in tooltip footer | | stepTransition | 'fade' \| 'slide' \| 'zoom' \| 'none' | 'fade' | Animation style for step transitions | | persistKey | string | - | LocalStorage key for auto-persisting completion | | persistProgress | boolean | false | Resume tour from last step (requires persistKey) | | scrollOffset | number | 0 | Scroll offset when scrolling to target | | disableKeyboard | boolean | false | Disable keyboard navigation | | disableScrollIntoView | boolean | false | Disable auto-scroll to target | | className | string | - | Custom class for root element | | overlayClassName | string | - | Custom class for overlay | | tooltipClassName | string | - | Custom class for tooltip |

Step Interface

interface Step {
  /** CSS selector or React ref to target element */
  target: Target;
  
  /** Tooltip title */
  title?: string;
  
  /** Tooltip content (supports React nodes) */
  content?: React.ReactNode;
  
  /** Tooltip placement relative to target */
  placement?: Placement;
  
  /** Auto-advance delay in milliseconds (0 = disabled) */
  autoAdvanceDelay?: number;
  
  /** Custom tooltip render function */
  renderTooltip?: (props: TooltipRenderProps) => React.ReactNode;
  
  /** Custom controls render function */
  renderControls?: (props: ControlsRenderProps) => React.ReactNode;
  
  /** Custom spotlight render function */
  renderSpotlight?: (props: SpotlightRenderProps) => React.ReactNode;
  
  /** Additional step metadata */
  meta?: Record<string, unknown>;
}

Placement options: top, bottom, left, right, top-start, top-end, bottom-start, bottom-end, left-start, left-end, right-start, right-end, auto

🎨 Examples

Basic Usage

import { Voyage } from 'react-voyage';
import 'react-voyage/style.css';

const steps = [
  {
    target: '#feature-1',
    title: 'Welcome!',
    content: 'This is your first feature.',
    placement: 'bottom',
  },
  {
    target: '#feature-2',
    title: 'Another Feature',
    content: 'Here is another important feature.',
    placement: 'right',
  },
];

<Voyage steps={steps} active={active} onEnd={() => setActive(false)} />

Dark Mode

<Voyage 
  steps={steps} 
  active={active} 
  theme="dark"
  onEnd={() => setActive(false)} 
/>

Using React Refs

const featureRef = useRef<HTMLDivElement>(null);

const steps = [
  {
    target: featureRef,
    title: 'Feature',
    content: 'This feature uses a React ref instead of a selector.',
  },
];

Custom Tooltip

const steps = [
  {
    target: '#feature',
    renderTooltip: ({ step, onNext, onPrev, isFirst, isLast }) => (
      <div className="custom-tooltip">
        <h2>{step.title}</h2>
        <p>{step.content}</p>
        <div className="custom-controls">
          {!isFirst && <button onClick={onPrev}>Back</button>}
          <button onClick={onNext}>
            {isLast ? 'Finish' : 'Next'}
          </button>
        </div>
      </div>
    ),
  },
];

Auto-Advance

const steps = [
  {
    target: '#feature',
    title: 'Auto-advancing',
    content: 'This step will auto-advance in 3 seconds.',
    autoAdvanceDelay: 3000,
  },
];

Custom Spotlight

const steps = [
  {
    target: '#feature',
    title: 'Custom Spotlight',
    content: 'This step has a custom spotlight effect.',
    renderSpotlight: ({ rect, borderRadius, padding }) => (
      <div 
        style={{
          width: rect.width + padding * 2,
          height: rect.height + padding * 2,
          borderRadius,
          border: '2px solid #ff6b6b',
          boxShadow: '0 0 20px rgba(255, 107, 107, 0.5)',
        }}
      />
    ),
  },
];

🎮 Live Demo

Try the Live Demo →

Or run locally:

# Clone the repo
git clone https://github.com/sirivatd/react-voyage.git
cd react-voyage

# Install dependencies
pnpm install

# Run the demo
pnpm demo

The demo will open at http://localhost:3002 and showcase all features.

🎨 Customization

Theming

// Light mode
<Voyage steps={steps} active={active} theme="light" />

// Dark mode
<Voyage steps={steps} active={active} theme="dark" />

// Auto (respects system preference)
<Voyage steps={steps} active={active} theme="auto" />

Custom Overlay

<Voyage 
  steps={steps} 
  active={active}
  overlayOpacity={0.9}
  overlayColor="#1a1a1a"
  maskPadding={16}
  borderRadius={12}
/>

Render Overrides

Every part of the UI can be customized via render props:

• renderTooltip - Full control over tooltip UI
• renderControls - Custom navigation buttons
• renderSpotlight - Custom spotlight effects

See the Examples section for code samples.

♿ Accessibility

react-voyage is built with accessibility in mind:

Keyboard Navigation

• Escape - Close tour
• Enter / ArrowRight - Next step
• ArrowLeft - Previous step
• Tab - Navigate within tooltip (focus trapped)

ARIA Support

• role="dialog" on tooltip
• aria-modal="true"
• aria-labelledby and aria-describedby for screen readers
• aria-live regions for step announcements

Motion Preferences

Automatically respects prefers-reduced-motion media query, disabling spring animations for users who prefer reduced motion.

Focus Management

Focus automatically moves to the tooltip when a step changes, ensuring keyboard users can immediately interact with controls.

📊 Comparison

| Feature | react-voyage | react-joyride | shepherd.js | intro.js | |---------|--------------|---------------|-------------|----------| | Bundle Size (gzipped) | < 15kb | ~25kb | ~30kb | ~20kb | | Liquid Spotlight | ✅ SVG morphing | ❌ Box shadow | ❌ Box shadow | ❌ Box shadow | | Glassmorphism UI | ✅ Built-in | ❌ | ❌ | ❌ | | Zero Config | ✅ | ⚠️ Requires setup | ⚠️ Requires setup | ⚠️ Requires setup | | TypeScript | ✅ Full support | ✅ | ⚠️ Partial | ❌ | | SSR-Safe | ✅ | ✅ | ⚠️ | ⚠️ | | Custom Render Props | ✅ Full control | ⚠️ Limited | ❌ | ❌ | | Dark Mode | ✅ Built-in | ⚠️ Manual | ⚠️ Manual | ⚠️ Manual | | Accessibility | ✅ WCAG compliant | ✅ | ⚠️ | ⚠️ | | Framer Motion | ✅ Spring physics | ❌ | ❌ | ❌ |

Why choose react-voyage?

• 🏆 Smallest bundle - 40% smaller than alternatives
• 💧 Unique liquid spotlight - Only library with SVG mask morphing
• ⚡ Best DX - Zero config, works in 30 seconds
• 🎨 Most customizable - Render props for everything

📦 Bundle Size

• Gzipped: < 15kb (excluding peer deps)
• Minified: ~45kb (excluding peer deps)
• Peer deps: react, react-dom, framer-motion

View on Bundlephobia →

🗺️ Roadmap

• [x] Tour persistence (save progress to localStorage)
• [ ] Analytics hooks (track tour completion)
• [x] Multi-step animations (choreographed sequences)
• [ ] Tour templates (pre-built tours for common patterns)
• [ ] React Native support
• [ ] Vue.js port

View full roadmap →

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Star the repo ⭐ - It helps others discover the project
2. Report bugs 🐛 - Open an issue with reproduction steps
3. Suggest features 💡 - Share your ideas in discussions
4. Submit PRs 🔧 - Fix bugs or add features

Development Setup

# Clone the repo
git clone https://github.com/sirivatd/react-voyage.git
cd react-voyage

# Install dependencies
pnpm install

# Run type checking
pnpm run typecheck

# Build
pnpm run build

See CONTRIBUTING.md for detailed guidelines.

📄 License

MIT © [Your Name]

See LICENSE for details.

🙏 Acknowledgments

Built with amazing open-source tools:

• Framer Motion - Animation library with spring physics
• Floating UI - Tooltip positioning engine
• Tailwind CSS - Utility-first CSS framework

⭐ Show Your Support

If you find react-voyage useful, please consider:

• ⭐ Starring the repo - It helps others discover the project
• 🐦 Sharing on Twitter - Tag @react_voyage (if you build something cool!)
• 💬 Joining discussions - Share your use cases and ideas
• ☕ Sponsoring - Help maintain the project

Made with ❤️ by the open-source community

View on GitHub • Live Demo