Tour

https://onboarding-tour.vercel.app/docs
Admin
Tour is an onboarding tour component built for shadcn/ui that enables developers to create guided,...
Tokens:2,802
Snippets:25
Trust Score:7.8
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install Tour Component

Source: https://onboarding-tour.vercel.app/docs

Command to install the tour component into a shadcn/ui project using various package managers.

```shell
pnpm dlx shadcn@latest add @tour/tour
```

--------------------------------

### Control Tour with useTour Hook

Source: https://onboarding-tour.vercel.app/docs

Use the useTour hook to programmatically start a specific tour by its ID from any component.

```typescript
"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>
}
```

--------------------------------

### Trigger Specific Tours via useTour Hook

Source: https://onboarding-tour.vercel.app/docs/examples/multiple-tours

Demonstrates how to programmatically start a specific tour by passing its unique ID to the tour.start() method provided by the useTour hook.

```tsx
"use client"
 
import { Button } from "@/components/ui/button"
import { useTour } from "@/components/ui/tour"
 
export function TourButtons() {
    const tour = useTour()
 
    return (
        <div>
            <Button onClick={() => tour.start("onboarding")}>
                Start Onboarding
            </Button>
            <Button onClick={() => tour.start("settings-guide")}>
                Settings Guide
            </Button>
        </div>
    )
}
```

--------------------------------

### useTour Hook

Source: https://onboarding-tour.vercel.app/docs/api

The useTour hook provides programmatic control over starting and closing tours within your components.

```APIDOC
## useTour Hook

### Description
The `useTour` hook provides methods to control the tour's visibility and flow.

### Return Value
- **start** ((tourId: string) => void) - Function to start a specific tour by its ID.
- **close** (() => void) - Function to close the current tour.

### Example
const { start, close } = useTour();

// Start a tour
start('onboarding-tour');

// Close the tour
close();
```

--------------------------------

### Define Multipage Tour Steps in TypeScript

Source: https://onboarding-tour.vercel.app/docs/examples/multipage

This example demonstrates how to define tour steps for a multipage tour using TypeScript. It utilizes the `Step` type and specifies `nextRoute` and `previousRoute` properties to control navigation between pages. Ensure the `Step` type is imported correctly from '@/components/ui/tour'.

```typescript
import { type Step } from "@/components/ui/tour"
 
export const steps = [
    {
        id: "home-hero",
        title: "Welcome",
        content: "Welcome to our application! Let's start the tour.",
        nextRoute: "/dashboard", // Navigate to dashboard on next
    },
    {
        id: "dashboard-stats",
        title: "Dashboard",
        content: "Here you can see your key metrics and statistics.",
        previousRoute: "/", // Navigate back to home on previous
        nextRoute: "/settings", // Navigate to settings on next
    },
    {
        id: "settings-profile",
        title: "Settings",
        content: "Customize your profile and preferences here.",
        previousRoute: "/dashboard", // Navigate back to dashboard
    },
] satisfies Step[]
```

--------------------------------

### Highlight Multiple Elements in a Tour Step

Source: https://onboarding-tour.vercel.app/docs/examples/multiple-elements

This example demonstrates how to assign the same 'data-tour-step-id' attribute to multiple DOM elements to group them in a single tour step. The steps configuration file then references this ID to trigger the highlight across all associated elements.

```tsx
export default function Page() {
    return (
        <div>
            <header data-tour-step-id="navigation">
                <nav>
                    <a href="/">Home</a>
                    <a href="/about">About</a>
                </nav>
            </header>
 
            <aside data-tour-step-id="navigation">
                <ul>
                    <li>Dashboard</li>
                    <li>Settings</li>
                </ul>
            </aside>
 
            <main>
                <h1>Welcome</h1>
            </main>
        </div>
    )
}
```

```typescript
import { type Step } from "@/components/ui/tour"
 
export const steps = [
    {
        id: "navigation",
        title: "Navigation Areas",
        content: "Both the header and sidebar will be highlighted.",
    },
] satisfies Step[]
```

--------------------------------

### Configure TourProvider

Source: https://onboarding-tour.vercel.app/docs

Wrap the application with the TourProvider to enable global tour context and define tour sequences.

```typescript
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>
}
```

--------------------------------

### Target Elements for Tour Steps

Source: https://onboarding-tour.vercel.app/docs

Apply the data-tour-step-id attribute to HTML elements to associate them with specific tour steps.

```html
<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>
```

--------------------------------

### Step Configuration

Source: https://onboarding-tour.vercel.app/docs/api

Defines the structure of a tour step, including positioning, content, and navigation behavior.

```APIDOC
## Step Object

### Description
Each step in the tour defines the content and behavior for a specific target element.

### Properties
- **id** (string) - Required - Unique identifier matching `data-tour-step-id`.
- **title** (React.ReactNode) - Required - Title displayed in the tour card.
- **content** (React.ReactNode) - Required - Content displayed in the tour card.
- **side** ("top" | "bottom" | "left" | "right") - Optional - Preferred side of the anchor.
- **sideOffset** (number) - Optional - Distance in pixels from the anchor.
- **align** ("start" | "center" | "end") - Optional - Alignment against the anchor.
- **nextRoute** (string) - Optional - Route to navigate to on next.

### Example
{
  "id": "welcome-step",
  "title": "Welcome",
  "content": "This is the start of your tour.",
  "side": "bottom"
}
```

--------------------------------

### TourProvider Component

Source: https://onboarding-tour.vercel.app/docs/api

The TourProvider component acts as the main container that wraps your application to provide tour context and configuration.

```APIDOC
## TourProvider

### Description
The `TourProvider` component is the main container that provides tour functionality to your application.

### Props
- **tours** (Tour[]) - Required - Array of tours configuration.
- **children** (React.ReactNode) - Required - Content to wrap with the tour context.

### Request Example
<TourProvider tours={myTours}>
  <App />
</TourProvider>
```

--------------------------------

### Define Multiple Tours Configuration

Source: https://onboarding-tour.vercel.app/docs/examples/multiple-tours

Defines an array of tour objects with unique IDs and step sequences. This configuration is typed using the Tour interface and serves as the source of truth for all available tours.

```typescript
import { type Tour } from "@/components/ui/tour"
 
export const tours = [
    {
        id: "onboarding",
        steps: [
            {
                id: "welcome",
                title: "Welcome!",
                content: "Welcome to our app. Let's get you started.",
            },
            {
                id: "dashboard",
                title: "Your Dashboard",
                content: "This is your main dashboard.",
            },
        ],
    },
    {
        id: "settings-guide",
        steps: [
            {
                id: "profile",
                title: "Profile Settings",
                content: "Customize your profile here.",
            },
            {
                id: "preferences",
                title: "Preferences",
                content: "Set your app preferences",
            },
        ],
    },
] satisfies Tour[]
```

--------------------------------

### Register Tours in Root Layout

Source: https://onboarding-tour.vercel.app/docs/examples/multiple-tours

Integrates the defined tours into the application by wrapping the root layout with the TourProvider component. This makes the tour data accessible throughout the component tree.

```tsx
import { TourProvider } from "@/components/ui/tour"
import { tours } from "@/lib/tours"
 
export default function RootLayout() {
    return <TourProvider tours={tours}>{/* Your app content */}</TourProvider>
}
```

--------------------------------

### Define Custom Tour Steps with TypeScript

Source: https://onboarding-tour.vercel.app/docs/examples/customization

This snippet demonstrates how to define an array of tour steps using the Step type. It showcases how to apply custom positioning, styling via className, and custom button labels with icons.

```typescript
import { type Step } from "@/components/ui/tour"
import { ArrowRightIcon, CheckIcon } from "lucide-react"
 
export const steps = [
    {
        id: "positioning",
        title: "Positioning",
        content:
            "Each tour step uses the Popover component, so you can pass any props supported by Popover Content.",
        side: "bottom",
        sideOffset: 10,
        align: "start",
        alignOffset: 10,
    },
    {
        id: "styling",
        title: "Custom Styling",
        content: "Apply your own styles to the tour step using className.",
        className: "w-96 bg-destructive",
    },
    {
        id: "buttonLabels",
        title: "Custom Button Labels",
        content:
            "Customize the labels of the next and previous buttons on each step.",
        previousLabel: <>← Previous Step</>,
        nextLabel: (
            <>
                Complete Tour <CheckIcon />
            </>
        ),
    },
] satisfies Step[]
```
Tokens:
Raw