Sections

Utilities

Forms

Hooks

useIsMobileNew

Tour

Displays a guided tour of the application.

Installation


pnpm dlx shadcn@latest add @shark/tour

Anatomy


Tour
├── TourTrigger
├── TourActionTrigger
├── TourOverlay
└── TourContent
    ├── TourSpotlight
    ├── TourHeader
    │   ├── TourProgressText
    │   ├── TourTitle
    │   └── TourDescription
    ├── TourBody
    ├── TourFooter
    │   ├── TourActions
    │   ├── TourPreviousStep
    │   └── TourNextStep
    └── TourClose

Usage


import { 
  Tour, 
  TourTrigger, 
  TourContent, 
  TourHeader,
  TourProgressText,
  TourTitle,
  TourDescription,
  TourFooter,
  TourNextStep,
  TourPreviousStep,
} from "@/components/ui/tour";


<Tour steps={steps}>
  <TourTrigger>Open Tour</TourTrigger>
  <TourContent>
    <TourHeader>
      <TourProgressText />
      <TourTitle />
      <TourDescription />
    </TourHeader>
  </TourContent>
  <TourFooter>
    <TourNextStep />
    <TourPreviousStep />
  </TourFooter>
</Tour>

Examples

Step Types

Demonstrate all three step types in a single tour: dialog for welcome/completion, tooltip anchored to elements, and floating for fixed-position content.

Target Element

Progress

Display a visual progress indicator at the bottom of the tour content showing how far along the user is.

Skip

Allow users to skip the entire tour at any step by adding a skip action.

Item 1

Item 2

Item 3

Enable arrow key navigation between tour steps using the keyboardNavigation prop.

Use arrow keys to navigate, Escape to close

Step 1

Step 2

Step 3

Events

Listen to tour lifecycle events like onStepChange and onStatusChange to track user progress.

Event Log:Start the tour to see events

Wait for Click

Use the effect function with waitForEvent to wait for user interaction before proceeding to the next step.

Wait for Input

Create form tutorials that wait for users to enter valid input before advancing.

I accept the terms and conditions

Wait for Element

Wait for dynamically rendered elements to appear in the DOM before showing a step.

Item 1

Item 2

Async

Load data asynchronously and update step content before displaying it using the effect function with show() and update().

User Profile Card

Custom spacing

Use [--space:--spacing("value")] on TourContent to adjust internal spacing.

Default spacing is --spacing(4).

You can use breakpoint utilities to change the internal spacing at different screen sizes.


  md:[--space:--spacing(6)] lg:[--space:--spacing(8)]

API Reference

Tour

Prop	Type	Default
`steps`	`TourStepDetails[]`	`[]`
`lazyMount`	`boolean`	`true`
`unmountOnExit`	`boolean`	`true`
`keyboardNavigation`	`boolean`	-
`onStepChange`	`(details: { stepId: string \| null }) => void`	-
`onStatusChange`	`(details: { status: string }) => void`	-
`immediate`	`boolean`	-
`present`	`boolean`	-
`onExitComplete`	`() => void`	-

TourTrigger

Prop	Type	Default
`className`	`string`	-

TourContent

Prop	Type	Default
`showCloseButton`	`boolean`	`true`
`className`	`string`	-
`asChild`	`boolean`	-

Attribute	Default
`--space`	`--spacing(4)`

TourHeader

Prop	Type	Default
`className`	`string`	-

TourTitle

Prop	Type	Default
`className`	`string`	-

TourDescription

Prop	Type	Default
`className`	`string`	-

TourProgressText

Prop	Type	Default
`className`	`string`	-

TourFooter

Prop	Type	Default
`className`	`string`	-

TourActions

Prop	Type	Default
`className`	`string`	-

TourPreviousStep

Prop	Type	Default
`asChild`	`boolean`	-

TourNextStep

Prop	Type	Default
`asChild`	`boolean`	-

TourClose

Prop	Type	Default
`asChild`	`boolean`	-

useTourContext

Return	Type
`tour`	`UseTourReturn`
`handleStart`	`() => void`

For a complete list of props, see the Ark UI documentation.

Tooltip

Tree View