Product Tour

Demo & usage

More examples

<sv-product-tour-pro
  variant="spotlight"
  [steps]="steps"
  [active]="touring"
  [stepIndex]="0"
  (stepChange)="onStep($event)" />

<!-- The tour never navigates: it asks, and you route. Give the step a
     route and the tour emits (routeRequest) the moment that step
     becomes current, then WAITS for its targetSelector to render on
     the new page and anchors to it. Without the wait the target does
     not exist yet when the step arrives, and the step loses its
     spotlight for the rest of the tour. -->
<sv-product-tour-pro
  variant="spotlight"
  [steps]="steps"
  [(active)]="touring"
  [awaitTargetMs]="3000"
  (routeRequest)="router.navigateByUrl($event.route)"
  (targetMissing)="skipStep($event)" />

<!-- The tour stores its progress in a versioned envelope under
     persistKey: the step by ID (never an index - inserting a step
     shifts every index after it), the checklist ticks, and whether
     the user completed or dismissed it.

     It never decides whether to show itself: handle
     (progressRestored) and let your own flag, cohort or "seen" table
     decide what [active] should be. -->
<sv-product-tour-pro
  tourId="onboarding"
  [tourVersion]="2"
  persistKey="sv-tour-onboarding"
  resume="step"
  [(active)]="touring"
  [steps]="steps"
  (progressRestored)="onProgress($event)" />

onProgress(e: SvTourProgressRestored) {
  // 'completed' or 'dismissed' is the "don't show this again" that
  // nothing used to record. They are different facts: someone who
  // skipped may want it back, someone who finished will not.
  if (e.progress.status === 'completed') this.touring.set(false);

  // Why the tour is on the step it is on:
  //   'resumed'         - back where they were
  //   'policy'          - resume="restart", or nothing stored
  //   'step-missing'    - that step no longer exists, so it restarted
  //   'version-changed' - tourVersion moved on; the position is void
  //   'declined'        - resume="never"
  this.analytics.track('tour_resume', { reason: e.reason, at: e.index });
}

steps = [
  { id: 'welcome', title: 'Welcome', content: 'Here is your dashboard.' },
  {
    id: 'invoices',
    title: 'Your invoices',
    content: 'Everything you have billed.',
    route: '/invoices',              // asked for, not navigated to
    targetSelector: '#invoice-table', // waited for, then anchored
  },
];

When to use

• Onboarding new users or introducing a new feature with guided steps.
• You want spotlight/tooltip/beacon/checklist styles over real UI.
• For a single announcement, an Alert Banner or Modal is enough.

Async states

None — this component has nothing to load, so it has no loading, empty or error state to drive.

Saved state

Stored kinds

• sv-product-tour/progress

What you will find under your own storage key. You choose the key; the blob names its own kind and schema version, so a component never reads state another one wrote.

Reading it back

Restore through the component's own restore… helper rather than casting the parsed JSON. A blob from an older release is migrated where it can be and refused with a reason where it cannot — so an upgrade never silently applies last month's shape to this month's fields.

Outputs

<sv-product-tour-pro>

Also in this family — SvProductTourProComponent from @styloviz-pro/product-tour.

Inputs

Outputs

Customization & theming

• Spotlight, tooltip, beacon and checklist styles.
• Configurable padding and opacity.
• Step progress and skip controls.
• Progress that survives a reload: `persistKey` + `tourId` store the step BY ID (never an index — inserting a step shifts every index after it), the checklist ticks and whether the tour was completed or dismissed, inside the same versioned envelope six other families use. `resume` decides what an interrupted tour does — `step`, `restart` or `never` — and `(progressRestored)` reports which happened and why. The tour never opens itself: that stays the host's `[active]`.
• Schema staleness: `[tourVersion]` versions the steps and `[expectedVersion]` is what the host says its UI is at — a mismatch emits `(schemaStale)`, because only the host can know a screen was rebuilt.
• Responsive: the tooltip / beacon cards cap their width to the viewport, so they stay fully on-screen even on the narrowest phones.
• Route-aware orchestration: `TourStep.route` + `(routeRequest)` ask the host to navigate (the tour never routes itself), `[awaitTargetMs]` bounds the wait for the new page to render the step's target, and `(targetMissing)` reports a target that never came. A step with no anchor at all centres its card and drops the arrow rather than pointing at whatever the previous step was on.

Best practices

• Do: Pick the variant from how much of the screen you are entitled to take, not from how it looks. FOUR of the eight dim the page, trap Tab and declare `aria-modal` — `modal`, `slideshow`, `tooltip`, `spotlight` — and the claim is honest because the overlay stack marks the background inert. The other four are ambient and take nothing: `progress-steps` (a bar and a card over a live page — it was documented as modal-like and never was), `checklist`, `announcement`, and `beacon`, whose popover is a `role="dialog"` without `aria-modal` because a labelled popup is not a claim on the page. Mixing the two models in one onboarding flow means the keyboard contract changes under the user mid-tour.
• Do: Keep tours short (3–5 steps) and always offer a Skip.
• Do: Persist completion so users don't see the same tour repeatedly.
• Tip: Anchor steps to stable elements so the spotlight lands accurately.
• Do: Handle `(routeRequest)` if any step sets `route` — the tour asks, you navigate. It deliberately does not touch the router: only your app knows whether the jump needs params, passes a guard, or should be refused. It then waits for the step's `targetSelector` to appear on the new page and anchors to it.
• Do: Give the tour a `tourId` and a `persistKey` if it is longer than a couple of steps — a tour interrupted by a reload had no defined behaviour, and the record is what "don't show this again" reads. Bump `[tourVersion]` whenever you change the steps: a stored position from another version is not adoptable, because the stored step id may still exist and mean something different.
• Do: Handle `(targetMissing)` rather than letting a step point at nothing. It fires when a `targetSelector` never appears within `awaitTargetMs` (default 3000) — the only party that can decide between skipping the step, ending the tour and accepting an unanchored card is you.

Accessibility

• Four variants are modal: **modal, slideshow, spotlight, tooltip**. Each dims the page, is `role="dialog"` + `aria-modal="true"`, moves focus into the card on open, traps Tab, marks the rest of the page `inert`, and restores focus on close.
• **checklist, announcement, beacon and progress-steps are ambient** — no backdrop, no trap, no inertness. The page behind them stays usable, which is the point of choosing them, and focus stays where the user left it. checklist, progress-steps and announcement are named `role="region"` landmarks (labelled by `tourTitle`, or the announcement's title) so a screen-reader user can find the surface that appeared, and progress-steps marks the current step `aria-current="step"`. ⚠️ `progress-steps` USED TO TRAP TAB, and this documentation claimed it was modal: it renders a top bar and a card and dims nothing, so trapping made it a keyboard trap in reverse — a mouse user could reach the page it describes and a keyboard user could not.
• Arrow keys move between steps, except when focus is in a field that has its own use for them (an input, textarea, select, contenteditable, or a listbox/combobox/menu/slider role) — the caret wins there, not the tour.
• Esc skips the tour when `allowSkip` is on, and closes a beacon card when one is open. The tour defers Esc to anything opened OVER it, so a select inside the card closes first.