How to Build a Product Tour in Angular — and What Stays Hard Afterwards

The Real Surface Area

Before the code, the honest scope. Most estimates cover the first two rows of this table, which is why the classic one-sprint tour turns into a recurring line item.

An Angular tour is a service, a directive registry and a CDK overlay — the router and persistence are the parts you own entirely.

1. Register Targets With a Directive, Not a Selector

This is the single decision that separates an Angular tour that ages well from one that quietly rots. The obvious approach is to put CSS selectors in your step config and call document.querySelector. It works, and then a design-system upgrade renames a class and step four silently stops anchoring — silently, because a missing element is not an exception.

A directive inverts the dependency. The component that owns the element declares that it is a tour target, and the tour service never touches the DOM by name.

import { Directive, ElementRef, Input, OnDestroy, OnInit, inject } from '@angular/core'
import { TourService } from './tour.service'

@Directive({ selector: '[appTourTarget]', standalone: true })
export class TourTargetDirective implements OnInit, OnDestroy {
  @Input('appTourTarget') id!: string

  private el   = inject(ElementRef<HTMLElement>)
  private tour = inject(TourService)

  ngOnInit()    { this.tour.registerTarget(this.id, this.el) }
  ngOnDestroy() { this.tour.unregisterTarget(this.id) }
}

<button appTourTarget="save-report" class="btn-primary">
  Save report
</button>

Now a refactor that deletes the button also deletes the registration, and a step pointing at save-report knows immediately that its target is gone rather than pointing at nothing. You can also assert in a unit test that every id referenced by the step config is registered somewhere in the app — a check that is impossible with raw selectors.

2. The Tour Service

One injectable, provided in root, holding the state as signals. Anything in the application — a settings button, a route guard, an analytics callback — can start or stop the tour by injecting it.

@Injectable({ providedIn: 'root' })
export class TourService {
  private targets = new Map<string, ElementRef<HTMLElement>>()
  private registry = signal(0)                     // bumped on every register/unregister

  readonly steps  = signal<TourStep[]>([])
  readonly index  = signal(-1)
  readonly status = signal<'idle' | 'running' | 'paused' | 'done'>('idle')

  readonly current = computed(() => this.steps()[this.index()] ?? null)
  readonly isLast  = computed(() => this.index() === this.steps().length - 1)

  /** Recomputes whenever the registry changes — no polling. */
  readonly currentTarget = computed(() => {
    this.registry()
    const step = this.current()
    return step ? this.targets.get(step.targetId) ?? null : null
  })

  registerTarget(id: string, el: ElementRef<HTMLElement>) {
    this.targets.set(id, el)
    this.registry.update(n => n + 1)
  }

  unregisterTarget(id: string) {
    this.targets.delete(id)
    this.registry.update(n => n + 1)
  }
}

The registry counter is the trick worth stealing. A Map is not reactive, so bumping a signal on every mutation gives you a currentTarget computed that recalculates the moment a late-rendering component registers itself. No MutationObserver, no polling interval — the target simply appears.

3. Positioning With the CDK Overlay

Do not write this yourself. FlexibleConnectedPositionStrategy already implements the behaviour you would spend two days rebuilding badly: preferred placement, ordered fallbacks, pushing back into the viewport, and repositioning on scroll.

private overlay = inject(Overlay)
private ref?: OverlayRef

show(target: ElementRef<HTMLElement>, step: TourStep) {
  this.ref?.dispose()

  const position = this.overlay.position()
    .flexibleConnectedTo(target)
    .withPositions([
      { originX: 'center', originY: 'bottom', overlayX: 'center', overlayY: 'top',    offsetY: 12 },
      { originX: 'center', originY: 'top',    overlayX: 'center', overlayY: 'bottom', offsetY: -12 },
      { originX: 'end',    originY: 'center', overlayX: 'start',  overlayY: 'center', offsetX: 12 },
      { originX: 'start',  originY: 'center', overlayX: 'end',    overlayY: 'center', offsetX: -12 },
    ])
    .withPush(true)
    .withViewportMargin(8)

  this.ref = this.overlay.create({
    positionStrategy: position,
    scrollStrategy: this.overlay.scrollStrategies.reposition({ autoClose: false }),
    hasBackdrop: false,           // we draw our own — see the spotlight below
  })

  this.ref.attach(new ComponentPortal(TourStepComponent))
  target.nativeElement.scrollIntoView({ block: 'center', behavior: 'smooth' })
}

Two flags matter more than they look. scrollStrategies.reposition with autoClose: false keeps the tooltip glued to its target while the page scrolls instead of closing the overlay, which is the default behaviour for menus and exactly wrong for a tour. And withPush(true) is what stops a step near the viewport edge from rendering half off-screen.

4. The Spotlight Overlay

The CDK backdrop dims the whole page, which is not what a tour wants — a tour wants everything dimmed except the target. Four positioned divs around the element will do it, with tedious arithmetic and no rounded corners. An SVG mask does it in one element.

@Component({
  selector: 'app-tour-spotlight',
  standalone: true,
  template: `
    @if (rect(); as r) {
      <svg class="spotlight" [attr.width]="vw()" [attr.height]="vh()">
        <defs>
          <mask id="tour-hole">
            <rect [attr.width]="vw()" [attr.height]="vh()" fill="white" />
            <rect [attr.x]="r.x - 6"     [attr.y]="r.y - 6"
                  [attr.width]="r.width + 12" [attr.height]="r.height + 12"
                  rx="8" fill="black" />
          </mask>
        </defs>
        <rect [attr.width]="vw()" [attr.height]="vh()"
              fill="rgba(12,20,40,0.55)" mask="url(#tour-hole)" />
      </svg>
    }
  `,
  styles: [`
    .spotlight { position: fixed; inset: 0; z-index: 999; pointer-events: none; }
  `],
  changeDetection: ChangeDetectionStrategy.OnPush,
})

pointer-events: none is a product decision, not a styling one. With it, the user can click the highlighted control and complete the action the step is describing — which is what you want for a tour that teaches by doing. Without it, the tour is a slideshow the user watches. Prefer the former; a step that asks someone to actually click the thing is worth several that describe it.

Keeping the rectangle honest

The hole has to track the target through scrolls, resizes and layout shifts. This is where zone.js bites: a plain window.addEventListener('scroll') registered inside the zone triggers change detection on every scroll frame across your entire application.

private zone = inject(NgZone)

private track(el: HTMLElement) {
  this.zone.runOutsideAngular(() => {
    const update = () => {
      const r = el.getBoundingClientRect()
      // only re-enter the zone when the rect actually changed
      if (sameRect(r, this.lastRect)) return
      this.lastRect = r
      this.zone.run(() => this.rect.set(r))
    }

    const ro = new ResizeObserver(update)
    ro.observe(el)
    window.addEventListener('scroll', update, { passive: true, capture: true })
    window.addEventListener('resize', update, { passive: true })
    this.cleanup = () => { ro.disconnect(); /* remove listeners */ }
  })
}

capture: true on the scroll listener matters: scroll events from an inner scrollable container do not bubble to window, so without capture the spotlight drifts whenever the target lives inside a scrolling panel — a very common layout in Angular admin applications.

5. Lazy Routes and Navigation

A tour spanning more than one route has to cooperate with the router explicitly. With lazy-loaded modules the destination's components do not even exist until the chunk arrives, so "wait for the target" and "wait for the route" are two different waits.

constructor() {
  inject(Router).events.pipe(takeUntilDestroyed()).subscribe(event => {
    if (event instanceof NavigationStart && this.status() === 'running') {
      this.status.set('paused')
      this.overlay.hide()
    }
    if (event instanceof NavigationEnd && this.status() === 'paused') {
      const step = this.current()
      if (step?.route && !event.urlAfterRedirects.startsWith(step.route)) {
        return this.finish('abandoned')      // user navigated away from the tour
      }
      this.status.set('running')
      this.resolveCurrent()                  // the registry signal handles the rest
    }
  })
}

Hiding the overlay on NavigationStart rather than leaving it up is the detail users notice. A dimmed screen persisting across a page transition, with a tooltip pointing at a component that is being destroyed, reads as a broken application.

Persistence: not localStorage alone

The one-line version stores tourSeen: true in localStorage. It is wrong in a specific and very reportable way: local storage is per-browser and per-device. Onboard on a laptop, open the app on a desktop, and the entire tour runs again. So does a private window, a cleared cache, and every user in an organisation whose browser profiles reset overnight.

async markSeen(tourId: string, outcome: 'completed' | 'dismissed') {
  try {
    await firstValueFrom(
      this.http.patch('/api/me/onboarding', { [tourId]: { outcome, at: new Date().toISOString() } })
    )
  } catch {
    localStorage.setItem(`tour:${tourId}`, outcome)   // don't punish a network blip
  }
}

Record completed and dismissed as different outcomes. A tour people finish is doing its job; a tour people escape is a toll you charge every new user. A single boolean cannot tell you which one you have shipped.

What Stays Hard After It Works

The first version is genuinely quick in Angular. These are the things that arrive later, roughly in the order teams meet them.

Build It, or Configure It?

Both answers are defensible. The question is which problem you have.

The deciding question is not whether your team can build it. It is: when the copy of step three needs changing, who does it and how long until a user sees the change? If the honest answer is "an engineer, next sprint", you have picked the expensive option no matter how small the original estimate was. The arithmetic is laid out in build vs buy user onboarding.

Pre-Launch Checklist

Whichever route you choose, these are what separate a tour that helps from one dismissed in two clicks.

1. Every step is skippable, and the tour is always escapable — including when a target never registers.
2. Targets are directive ids, not CSS selectors, and a test asserts every configured id exists.
3. Scroll and resize tracking runs outside the zone, with a rect diff before re-entering.
4. Events fire on every transition, so you can read per-step drop-off rather than a completion rate.
5. Completion is stored on the user, with localStorage only as a fallback.
6. Dismissed and completed are distinct outcomes.
7. Escape closes, Tab is trapped, focus returns, steps are announced.
8. Tested at 375px and in your longest language.
9. The tour is short — five steps ending in one real action beat twelve narrating the navigation. The goal is activation, not coverage.

Frequently Asked Questions