9

Get Started

Next

An onboarding tour component built for shadcn/ui, following the same design patterns and styles.

Prerequisite

Before installing, make sure you already have shadcn/ui set up in your project.

Installation

pnpm dlx shadcn@latest add https://onboarding-tour.vercel.app/r/tour.json

Concepts

Tour

A Tour represents a complete onboarding flow or a guide for a specific feature. It is identified by a unique id and contains a sequence of steps. You can define multiple tours in your application (e.g., "onboarding", "new-feature-x", "settings-guide") and start them independently.

Step

A Step is a single card in the tour sequence. Each step targets specific elements on the page using the data-tour-step-id attribute.

Usage

Setup

First, wrap your application with the TourProvider component. This provides the tour context to your entire app:

app/layout.tsx
import { type Tour, TourProvider } from "@/components/ui/tour"
 
const tours = [
    {
        id: "main",
        steps: [
            {
                id: "welcome",
                title: "Welcome",
                content: "Let's take a quick tour of the main features.",
            },
            {
                id: "feature-1",
                title: "Feature One",
                content: "This is an important feature.",
            },
        ],
    },
] satisfies Tour[]
 
export default function RootLayout() {
    return <TourProvider tours={tours}>{/* Your app content */}</TourProvider>
}

Starting the Tour

Use the useTour hook to control the tour from anywhere in your app:

"use client"
 
import { Button } from "@/components/ui/button"
import { useTour } from "@/components/ui/tour"
 
export function StartTourButton() {
    const tour = useTour()
 
    return <Button onClick={() => tour.start("main")}>Start Tour</Button>
}

Targeting Elements

Add data-tour-step-id attributes to elements you want to highlight in the tour. The tour will automatically find and highlight elements matching the step's id:

<div data-tour-step-id="welcome">
    <h1>Welcome to My App</h1>
</div>
 
<div data-tour-step-id="feature-1">
    <p>This is a feature</p>
</div>
 
<div data-tour-step-id={["welcome", "feature-1"]}>
    <p>This element appears in both steps</p>
</div>