TourTorch

TourTorchDocumentation

Create beautiful, interactive onboarding experiences for your Next.js applications with ease

Easy Setup
TypeScript
Responsive
Customizable

Quick Start

Get up and running in minutes

1. Install

Install the required dependencies with your package manager

2. Setup

Add the TourProvider to your root layout component

3. Use

Create your first tour with the TourTrigger component

Installation

Install dependencies and setup components

Install Dependencies
Choose your preferred package manager
npm install @radix-ui/react-progress @radix-ui/react-separator
Copy TourTorch Component
Add the TourTorch component to your project
components/tour-torch.tsx

Copy the complete TourTorch component from our repository. It's a single, self-contained file with all functionality included.

Setup Provider
Add TourProvider to your root layout
import { TourProvider, TourOverlay } from "@/components/tour-torch"

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <TourProvider>
          {children}
          <TourOverlay />
        </TourProvider>
      </body>
    </html>
  )
}

Basic Usage

Create your first interactive tour

Your First Tour
Create a simple tour with just a few lines of code
import { TourTrigger } from "@/components/tour-torch"

const tourSteps = [
  {
    id: "welcome",
    title: "Welcome to TourTorch!",
    content: "Let's take a guided tour of your application's key features.",
    target: "#main-content",
    placement: "bottom"
  },
  {
    id: "navigation",
    title: "Navigation Menu",
    content: "Use this navigation menu to access different sections.",
    target: "#nav-menu",
    placement: "right"
  }
]

export default function MyPage() {
  return (
    <div>
      <TourTrigger steps={tourSteps}>
        Start Tour
      </TourTrigger>
      
      <main id="main-content">
        <nav id="nav-menu">
          {/* Your content */}
        </nav>
      </main>
    </div>
  )
}
Step Properties
Essential properties for each tour step
id
Required

Unique identifier for the step

title
Required

Step title displayed in tooltip

content
Required

Step description/instructions

target
Required

CSS selector for element to highlight

placement

Tooltip position (top, bottom, left, right)

Placement Options
Choose where to position your tooltips
top
bottom
left
right

Advanced Usage

Programmatic control and customization

Programmatic Control
Use the useTour hook for advanced tour management
import { useTour } from "@/components/tour-torch"

function MyComponent() {
  const { 
    startTour, 
    nextStep, 
    prevStep, 
    skipTour, 
    endTour,
    isActive,
    currentStep 
  } = useTour()

  const handleCustomTour = () => {
    startTour(customSteps)
  }

  return (
    <div>
      <button onClick={handleCustomTour}>
        Start Custom Tour
      </button>
      
      {isActive && (
        <div>Current step: {currentStep + 1}</div>
      )}
    </div>
  )
}
Hook Methods
Available methods from useTour hook
startTour(steps)

Start a new tour with steps

nextStep()

Go to next step

prevStep()

Go to previous step

skipTour()

Skip the current tour

endTour()

End the tour immediately

goToStep(index)

Jump to specific step

State Properties
Available state from useTour hook
isActive
boolean

Whether tour is currently running

currentStep
number

Current step index (0-based)

steps
TourStep[]

Array of all tour steps

API Reference

Complete reference for all components and hooks

TourStep Interface
Properties for defining tour steps
PropertyTypeRequiredDescription
idstringUnique identifier for the step
titlestringStep title displayed in tooltip
contentstringStep description/instructions
targetstringCSS selector for element to highlight
placement'top' | 'bottom' | 'left' | 'right'Tooltip position (default: 'bottom')

Examples

Real-world usage examples and demos

Onboarding Tour
Welcome new users to your application with a guided tour

Perfect for introducing new users to your app's key features and navigation.

View Demo
Feature Highlights
Showcase new features and updates to existing users

Great for announcing new features or guiding users through complex workflows.

View Demo

Best Practices

Guidelines for creating effective tours

Do's
Follow these guidelines for better user experience
Keep steps concise and focused on one action
Use clear, actionable language
Test on different screen sizes and devices
Always provide skip options for users
Focus on core features first
Use meaningful and descriptive step IDs
Test with real users to gather feedback
Make tours contextual and relevant
Don'ts
Avoid these common mistakes
Make tours too long (keep under 7 steps)
Use technical jargon or complex language
Force users through tours without skip options
Highlight every single feature at once
Use vague or unclear descriptions
Forget to test on mobile devices
Skip user testing and feedback collection
Create tours that interrupt critical workflows

Responsive Design

Works perfectly across all devices

Multi-Device Support
TourTorch automatically adapts to different screen sizes and orientations

Desktop

Full-featured experience with optimal positioning and larger tooltips

Tablet

Adapted layouts with touch-friendly controls and medium-sized tooltips

Mobile

Optimized for small screens with compact tooltips and touch interaction

Troubleshooting

Common issues and their solutions

Tour doesn't start
  • Ensure TourProvider wraps your entire app in layout.tsx
  • Check that target elements exist in the DOM when tour starts
  • Verify step IDs are unique within the tour
  • Make sure TourOverlay is included in your layout
Element not highlighted correctly
  • Check CSS selector syntax (use # for IDs, . for classes)
  • Ensure the target element is visible and not hidden
  • Try using ID selectors instead of class selectors for better reliability
  • Check for CSS z-index conflicts that might hide the highlight
Tooltip positioning issues
  • Try different placement options (top, bottom, left, right)
  • Check for CSS conflicts that might affect positioning
  • Ensure there's adequate viewport space for the tooltip
  • Test on different screen sizes to verify responsive behavior
Tour not responsive on mobile
  • Test placement options on different screen sizes
  • Use shorter content for mobile devices
  • Check that viewport meta tag is properly configured
  • Ensure touch events work properly on mobile devices
Need Help?
Get support and connect with the TourTorch community