import { WrTour } from 'ngwr/tour';WrTour
A guided tour that highlights one element at a time and explains it.
Installation
Import the class, and @use the entry point in your global styles. Nothing warns you when the @use is missing.
Run a tour
Pass the steps to start(). A step whose target is missing is skipped; Escape ends the tour.
this.tour.start([
{ target: '[data-tour="search"]', title: 'Start here', content: 'Type a name…' },
{ target: '[data-tour="filter"]', content: 'Filters stack.', placement: 'right' },
{ target: '[data-tour="save"]', content: 'Nothing is saved until you press this.', placement: 'top' },
]);Reading the state
Progress is exposed as signals.
tour.active(); // is a tour running
tour.index(); // 0-based step, -1 when idle
tour.total(); // step count
tour.step(); // the current WrTourStep | null
// Use these, not index() === 0: missing steps are skipped.
tour.isFirst(); // no step before this one
tour.isLast(); // no step after this oneAPI
| Name | Description | Type | Default |
|---|---|---|---|
WrTour | Injectable service. No component to place. | service | — |
start(steps) | Begin a tour. Restarts if one is running; a no-op under SSR. | (steps: readonly WrTourStep[]) => void | — |
next() | Advance. Past the last step it finishes the tour. | () => void | — |
prev() | Go back. Stays put on the first step. | () => void | — |
stop() | End the tour and return focus where it started. | () => void | — |
active | Whether a tour is running. | Signal<boolean> | false |
index | 0-based index of the current step, -1 when idle. | Signal<number> | -1 |
total | Step count of the running tour. | Signal<number> | 0 |
isFirst | No step before this one. Use it, not index() === 0, since missing steps are skipped. | Signal<boolean> | true |
isLast | No step after this one; decides between Next and Done. | Signal<boolean> | false |
step | The step being shown. | Signal<WrTourStep | null> | null |
WrTourStep | One stop on the tour. | interface | — |
target | A CSS selector or the element. A step that matches nothing is skipped. | string | HTMLElement | — |
title | Heading above the copy. | string | — |
content | The step's body text. | string | — |
placement | Preferred side. Falls back to the opposite side near a viewport edge. | 'top' | 'bottom' | 'left' | 'right' | 'bottom' |
panelClass | Extra classes on this step's overlay pane. | WrClassInput | — |
CSS variables
Set these on the element itself, with a rule more specific than its Declared on selector. In a global stylesheet, put a class of yours on an ancestor it really has: <body> for an overlay panel, which renders outside your markup. In a component stylesheet the selector alone works, but only for an element in that component's own template. A value on a wrapper or :root is shadowed, because ngwr/tour declares each default on its own element.
| Variable | Default | Declared on |
|---|---|---|
--wr-tour-popup-actions-gap | var(--wr-space-sm) | .wr-tour-popup |
--wr-tour-popup-border | var(--wr-border-base) | .wr-tour-popup |
--wr-tour-popup-content-font-size | var(--wr-text-sm) | .wr-tour-popup |
--wr-tour-popup-content-line-height | var(--wr-leading-normal) | .wr-tour-popup |
--wr-tour-popup-content-margin-bottom | var(--wr-space-lg) | .wr-tour-popup |
--wr-tour-popup-font-family | var(--wr-font-family-base) | .wr-tour-popup |
--wr-tour-popup-padding | var(--wr-space-lg) | .wr-tour-popup |
--wr-tour-popup-progress-font-size | var(--wr-text-xs) | .wr-tour-popup |
--wr-tour-popup-progress-margin-bottom | var(--wr-space-sm) | .wr-tour-popup |
--wr-tour-popup-radius | var(--wr-border-radius-base) | .wr-tour-popup |
--wr-tour-popup-title-font-size | var(--wr-text-base) | .wr-tour-popup |
--wr-tour-popup-title-font-weight | var(--wr-font-weight-semibold) | .wr-tour-popup |
--wr-tour-popup-title-margin-bottom | var(--wr-space-sm) | .wr-tour-popup |
--wr-tour-spotlight-radius | var(--wr-border-radius-base) | .wr-tour__spotlight |
Dependencies
See also
Component PopoverShow a template, or a text tooltip, next to its trigger.Component StepperA multi-step flow with numbered headers.Component ButtonA button for an action or a link.Guide OverlayStyle ngwr's floating panels and control where focus goes.Component InputA directive that styles a native <input> or <textarea>.