Sections

Components

Utilities

Forms

Hooks

useIsMobile

Tour

Copy Markdown

Displays a guided tour of the application.

Docs API

PreviewCode

Open

Installation#

CLIManual

pnpmbunnpmyarn

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.

PreviewCode

Start Tour Target Element

Progress#

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

PreviewCode

Start Tour

Step 1

Step 2

Step 3

Step 4

Skip#

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

PreviewCode

Start Tour

Item 1

Item 2

Item 3

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

PreviewCode

Start Tour

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.

PreviewCode

Start Tour

Step 1

Step 2

Step 3

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.

PreviewCode

Start Interactive Tour Add ItemEditDelete

Wait for Input#

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

PreviewCode

Start Form Tutorial

Name

I accept the terms and conditions

Wait for Element#

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

PreviewCode

Start Tour Add Item

Item 1

Item 2

Async#

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

PreviewCode

Start Tour User Profile Card

Custom spacing#

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

Default spacing is --spacing(4).

PreviewCode

Open

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 ](/docs/components/tooltip)[

Tree View ](/docs/components/tree-view)

On This Page

Installation Anatomy Usage Examples Step Types Progress Skip Keyboard Navigation Events Wait for Click Wait for Input Wait for Element Async Custom spacing API Reference Tour TourTrigger TourContent TourHeader TourTitle TourDescription TourProgressText TourFooter TourActions TourPreviousStep TourNextStep TourClose useTourContext