Tour
A guided tour component that highlights elements and provides step-by-step instructions to help users learn about your application.
Installation
pnpm dlx shadcn@latest add @diceui/tour
Layout
Import the parts, and compose them together.
import {
Tour,
TourPortal,
TourSpotlight,
TourSpotlightRing,
TourStep,
TourArrow,
TourClose,
TourHeader,
TourTitle,
TourDescription,
TourFooter,
TourStepCounter,
TourPrev,
TourNext,
TourSkip,
} from "@/components/ui/tour";
return (
<Tour>
<TourPortal>
<TourSpotlight />
<TourSpotlightRing />
<TourStep>
<TourArrow />
<TourClose />
<TourHeader>
<TourTitle />
<TourDescription />
</TourHeader>
<TourFooter>
<TourStepCounter />
<TourPrev />
<TourNext />
<TourSkip />
</TourFooter>
</TourStep>
</TourPortal>
</Tour>
)Examples
Controlled
A tour with controlled state management, allowing external control of the current step.
Custom Spotlight Styling
You can customize the appearance of the spotlighted element using the SpotlightRing component:
<Tour.Root open={open} onOpenChange={setOpen}>
<Tour.Portal>
<Tour.Spotlight />
{/* Border style */}
<Tour.SpotlightRing className="rounded-lg border-2 border-primary" />
{/* Ring with offset */}
<Tour.SpotlightRing className="rounded-xl ring-2 ring-blue-500 ring-offset-2" />
{/* Glowing effect */}
<Tour.SpotlightRing className="rounded-lg shadow-lg shadow-primary/50" />
{/* Animated pulse */}
<Tour.SpotlightRing className="rounded-lg border-2 border-primary animate-pulse" />
<Tour.Step target="#element">{/* ... */}</Tour.Step>
</Tour.Portal>
</Tour.Root>Global Offset Control
Set default spacing for all steps and override per step:
<Tour.Root
open={open}
onOpenChange={setOpen}
sideOffset={16} // Global default: 16px gap
alignOffset={0} // Global alignment offset
>
<Tour.Portal>
<Tour.Spotlight />
<Tour.SpotlightRing />
{/* Uses global sideOffset={16} */}
<Tour.Step target="#step-1" side="bottom">
<Tour.Header>
<Tour.Title>Step 1</Tour.Title>
</Tour.Header>
</Tour.Step>
{/* Overrides with custom sideOffset={32} */}
<Tour.Step target="#step-2" side="top" sideOffset={32}>
<Tour.Header>
<Tour.Title>Step 2 - Larger Gap</Tour.Title>
</Tour.Header>
</Tour.Step>
</Tour.Portal>
</Tour.Root>API Reference
Tour
The main container component for the tour that manages state and provides context.
Prop
Type
TourSpotlight
The spotlight backdrop that dims the page and highlights the target element with a cutout effect.
Prop
Type
| Data Attribute | Value |
|---|
TourSpotlightRing
A visual ring/border element that wraps around the spotlighted target element. Use this to add custom styling like borders, shadows, or animations to the highlighted area.
Prop
Type
| Data Attribute | Value |
|---|
TourStep
A single step in the tour that targets a specific element on the page.
Prop
Type
| Data Attribute | Value |
|---|
TourClose
Button to close the entire tour.
Prop
Type
TourHeader
Container for the tour step's title and description.
Prop
Type
TourTitle
The title of the current tour step.
Prop
Type
TourDescription
The description text for the current tour step.
Prop
Type
TourFooter
Container for tour navigation controls and step counter.
TourStepCounter
Displays the current step number and total steps.
Prop
Type
TourPrev
Button to navigate to the previous step.
Prop
Type
TourNext
Button to navigate to the next step or complete the tour.
Prop
Type
TourSkip
Button to skip the entire tour.
Prop
Type
TourArrow
An optional arrow element that points to the target element.
Prop
Type
Accessibility
Keyboard Interactions
| Key | Description |
|---|---|
| Escape | Triggers the onEscapeKeyDown callback. Default behavior closes the tour unless prevented. |
| Tab | Moves focus to the next focusable element within the tour content. |
| ShiftTab | Moves focus to the previous focusable element within the tour content. |
| EnterSpace | Activates the focused button (next, previous, skip, or close). |
Credits
- Radix UI Dismissable Layer - For the pointer down outside and interact outside event handling patterns.
- Radix UI Focus Guard - For the focus guard implementation.
- Radix UI Dialog - For the focus trap and auto-focus management patterns.