Tour

Guided coach marks over the real interface. Steps point at selectors, so a tour is data next to the copy it belongs to rather than refs threaded through every component it visits.

src/components/ui/tour.tsx

About

From the component's own source, where it was written.

Guided coach marks over the real interface.

Each step points at a selector rather than at a ref, so a tour can be defined as data next to the copy it belongs to instead of being threaded through every component it visits.

A step whose target is missing is skipped rather than shown floating in the middle of the page. Targets disappear all the time — a feature behind a flag, a panel that is closed — and a tour that stops dead on the first absent one is worse than a shorter tour.

The spotlight is a ring around the target drawn with a huge outline: one element, no four-panel overlay to keep in sync, and the target stays fully interactive because nothing covers it.

Install

npx astralyx-ui add tour

Usage

import { Tour } from '@/components/ui/tour'

<Tour open={open} onOpenChange={setOpen} steps={steps} />

Composer

Change the props and the source below follows.

Props

steps

tsx

<Tour
  open={open}
  onOpenChange={setOpen}
  steps={[{ target: '#publish', title: 'Publish', content: '…' }]}
/>

Examples

Coach marks

tsx

<Tour open={open} onOpenChange={setOpen} steps={steps} />

API

Generated from the source, so it cannot fall behind the code. One table per exported component, then hooks, functions and types.

`Tour`

Extends Omit<ComponentProps<'div'>, 'content'>.

Prop	Type	Default	Description
steps	TourStep[]	required	`{ target, title, content, side? }` where target is a CSS selector.
open	boolean	required	—
onOpenChange	(open: boolean) => void	required	—
onFinish	() => void	—	Fires on Done, on dismiss, and when no step can be shown.
backLabel	ReactNode	'Back'	—
endLabel	string	'End tour'	Accessible name for the dismiss button.
stepLabel	(index: number, total: number) => string	DEFAULT_STEP_LABEL	Accessible name for the progress dots.

Types

`TourStep`

Guided coach marks over the real interface.

Field	Type	Description
target	string	CSS selector for the element to point at.
title	ReactNode	—
content	ReactNode	—
side?	Side	—

Behaviour

Topic	Detail	Description
missing targets	skipped	A step whose element is absent is passed over rather than shown floating — targets disappear behind flags and closed panels all the time.
spotlight	outline	A ring drawn with a huge outline dims everything else in one element, and leaves the target fully interactive because nothing covers it.