Skip to content

Design system

Documentation

DesignComponents / Tour

Components / Tour

Stable

Tour

Guide users through optional target-aware steps with skip and completion actions.

On this page

Examples

Targeted steps

Open the tour to highlight the target and move through a short guide.

Targeted product tour

Target not found

A missing selector shows a recovery message and keeps the next step available.

Tour with missing target fallback

Try the tour

Inspect skip, previous, next, and completion actions.

Tour property playground

Usage

import { Tour } from "@phuctech/ui/components/tour";

<Tour open={tourOpen} onOpenChange={setTourOpen} steps={steps} onComplete={saveCompletion} />

Targets and fallback

Each optional target is a CSS selector. When found, Tour scrolls it into view, adds a temporary outline and data-tour-active marker, then restores the original inline outline when the step changes or closes. Invalid or missing selectors show a message and leave Next/Skip available. Tour uses the shared modal Dialog, so the guide itself remains the focused task while open.

API

Component API
PropTypeDefaultDescriptionConstraints
stepsreadonly TourStep[]requiredOrdered guide steps with stable IDs, titles, and descriptions.Provide at least one step to render the dialog.
open / defaultOpenbooleanfalseControlled or initial dialog state.Do not mix controlled and uncontrolled open state.
onOpenChange(open: boolean) => void—Reports dialog state changes.The feature owns when a tour should start again.
stepIndex / defaultStepIndexnumber0Controlled or initial step.Values are clamped to the available step range.
onStepChange(index: number) => void—Reports previous/next navigation.The feature owns persistence of progress.
onComplete / onSkip() => void—Called before the tour closes after finish or skip.Use completion only for an explicit user choice.
targetstring on TourStep—Optional CSS selector to scroll to and temporarily outline.A missing target is a recoverable step state.

Accessibility

The shared Dialog manages initial focus, focus containment, Escape handling, and focus restoration. The title and step count name the current task, and the footer exposes Skip, Previous, Next, or Finish as keyboard controls.

  • Dialog handles one blocking task or confirmation.
  • Tooltip adds a short hint without a multi-step flow.