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
npm install @radix-ui/react-progress @radix-ui/react-separatorCopy the complete TourTorch component from our repository. It's a single, self-contained file with all functionality included.
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
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>
)
}idUnique identifier for the step
titleStep title displayed in tooltip
contentStep description/instructions
targetCSS selector for element to highlight
placementTooltip position (top, bottom, left, right)
topbottomleftrightAdvanced Usage
Programmatic control and customization
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>
)
}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
isActiveWhether tour is currently running
currentStepCurrent step index (0-based)
stepsArray of all tour steps
API Reference
Complete reference for all components and hooks
| Property | Type | Required | Description |
|---|---|---|---|
| id | string | ✅ | Unique identifier for the step |
| title | string | ✅ | Step title displayed in tooltip |
| content | string | ✅ | Step description/instructions |
| target | string | ✅ | CSS selector for element to highlight |
| placement | 'top' | 'bottom' | 'left' | 'right' | ❌ | Tooltip position (default: 'bottom') |
Examples
Real-world usage examples and demos
Perfect for introducing new users to your app's key features and navigation.
View DemoGreat for announcing new features or guiding users through complex workflows.
View DemoBest Practices
Guidelines for creating effective tours
Responsive Design
Works perfectly across all devices
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
- 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
- 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
- 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
- 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