Tour
Tour walks people through the key parts of a product step by step: dims the rest, spotlights the right element and explains it with a TeachingPopover.
Each step takes a target (a CSS selector or a ref; without one, the popover sits in the middle of the screen), title, content, placement (top / bottom / start / end, flipped in RTL) and media. The popover is modal: focus moves inside and Tab can't leave it, Esc closes it, and focus returns to where it was when the tour ends. The target is scrolled into view and tracked every frame (scrolling, resizing). The spotlight has an outline, so it stays visible in high contrast mode. useTour() controls start / stop / next / back / goTo.
Yugen Labs · experimentalThis component is outside SemVer: its API can change in a minor release, and What's new says so. Versioning policy
Import
Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.
TSX
// npm install yugen-uiimport { Tour, useTour, type TourStep } from "yugen-ui";Variants
Each tile is a standalone example: hover to copy, or press Code to see the source.
Your dashboard
One step, controlled, brand
target is a ref; open / onOpenChange control the tour from outside.
Usage
Do
- Keep the tour short (3–5 steps), one idea per step.
- Always offer Skip, and let people reopen the tour from the Help menu.
- Target stable elements (id, data attribute) rather than class names that change easily.
Don't
- Don't open the tour on every visit. Only the first time, or when people ask for it.
- Don't put required actions inside the tour.
- Don't use a tour to make up for a confusing interface.
Props
| Prop · Type | Default | Description |
|---|---|---|
| steps{ target?, title, content, placement?, media? }[] | Default: — | Steps; target is a selector or a ref. |
| open / defaultOpen / onOpenChangeboolean | Default: — | Open state. |
| step / defaultStep / onStepChangenumber | Default: — | Current step (from 0). |
| onFinish() => void | Default: — | Called when Finish is clicked on the last step. |
| appearance"normal" | "brand" | Default: "normal" | Surface, as in TeachingPopover. |
| spotlightPadding / closeOnOverlayClicknumber / boolean | Default: 8 / false | Gap around the spotlight; close by clicking the overlay. |
| nextLabel / backLabel / skipLabel / finishLabelstring | Default: — | Button labels. |
| useTour | Default: — | Controls the tour from anywhere inside Tour. |
Messages
Text built into the component: labels, aria-labels, screen reader announcements.
English by default. Change it with the messages prop of YugenProvider, by the namespace below; messagesVi has the Vietnamese set. See Interface language.
messages.tour
| Key · Type | Default (English) | messagesVi |
|---|---|---|
| nextstring | Default (English)"Next" | messagesVi"Tiếp" |
| backstring | Default (English)"Back" | messagesVi"Quay lại" |
| skipstring | Default (English)"Skip" | messagesVi"Bỏ qua" |
| finishstring | Default (English)"Finish" | messagesVi"Hoàn tất" |
| roleDescriptionstring aria-roledescription của bề mặt hướng dẫn. | Default (English)"tour" | messagesVi"hướng dẫn" |
| stepstring Chữ ẩn (sr-only) trước số bước "1 / 3". | Default (English)"Step" | messagesVi"Bước" |