Tour
A guided walk through a screen: each step highlights an element and shows a card beside it with Back, Next and Skip.Basic
Preview
Code
Installation
Package
CLI (copy source)
pnpm
pnpm add @advui/corenpm
npm install @advui/coreUsage
import { Button, Tour } from '@advui/core'
const search = useRef(null)
<Search ref={search} />
<Tour
open={open}
onOpenChange={setOpen}
steps={[
{ title: 'Welcome', description: 'A quick look around.' },
{ target: search, title: 'Find anything', description: 'Search looks through every project.' },
]}
/>API reference
Tour
| Prop | Type | Default | Description |
|---|---|---|---|
steps required | TourStep[] | — | `{ target?, title, description? }`. `target` is a ref to the element the step points at; without one, the card is centered. |
open | boolean | — | Controlled open state. |
defaultOpen | boolean | false | Starts open. |
onOpenChange | (open: boolean) => void | — | Called when the tour opens or closes (Done, Skip, Escape, Android back). |
step | number | — | Controlled index of the current step, from 0. |
defaultStep | number | 0 | The step an uncontrolled tour starts on, and goes back to when closed. |
onStepChange | (step: number) => void | — | Called on Back and Next. |
onComplete | () => void | — | Called when Done is pressed on the last step, such as to remember the tour was seen. |
labels | Partial<TourLabels> | — | `next`, `back`, `done`, `skip` and `progress(step, count)` (“Step 2 of 4”). |
Accessibility
- On web, each step is a modal
dialognamed by its title and described by “Step 2 of 4” and its description. Focus moves to it on each step, Tab stays inside it, Escape closes it, and focus goes back to where it was. - On iOS and Android, the step and title are one heading, which takes screen reader focus on each step; the app behind is hidden from TalkBack and VoiceOver while the tour is open, and Android’s back button closes it.
- The highlighted element can still be pressed; the rest of the screen is covered.
- Do not hide anything only in a tour: it is for first runs, and can be skipped.
| Key | Action |
|---|---|
| Tab / Shift+Tab | Moves between Skip, Back and Next, inside the card. |
| Enter / Space | Presses the focused button. |
| Escape | Closes the tour. |
Platform notes
Web
Scrolls each target into view and follows it as the page scrolls or resizes.
iOS
Targets are measured from the root view (
measure) and not scrolled to: keep them on screen, or scroll in onStepChange.Android
Targets are measured from the root view (
measure), so the ring stays on its target under an edge-to-edge status bar, and not scrolled to: keep them on screen, or scroll in onStepChange. The back button closes the tour.