Build an Onboarding Tour / Product Walkthrough

By /
⏱ 2 min read

Product tours (Userflow, Pendo Guides, Intercom Tours, custom) walk new users through the UI to highlight key features. Done well, they accelerate activation. Done poorly, they annoy users. The interview tests whether you understand the technical patterns and the UX considerations.

Functional requirements

  • Sequence of steps, each pointing at a UI element
  • Step has text, optional image, optional action
  • Spotlight on the target element (rest dimmed)
  • Tooltip arrow points at target
  • Forward / Back / Skip buttons
  • Tour state persisted (don’t show twice)

Architecture

Three components:

  1. Tour engine: manages step sequence, current state
  2. Step overlay: dim background, spotlight, tooltip
  3. Target selector: resolves CSS selector to actual DOM element

Targeting elements

Each step has a CSS selector (or React ref):

{
  target: '#new-project-button',
  title: 'Create your first project',
  body: 'Click here to get started',
  position: 'bottom'
}

Use IDs or stable data attributes; class names break.

Spotlight effect

Dim the page except for the target element:

  • Full-screen dark overlay
  • Cut a hole around the target (SVG mask or CSS clip-path)
  • Target appears highlighted, rest dimmed

Library: react-joyride, intro.js, shepherd.js handle the math.

Tooltip positioning

Tooltip near the target. Use Floating UI for positioning (same library as tooltip / popover).

Auto-flip if not enough room. Auto-shift if near viewport edge.

Step transitions

Smooth transition when moving between steps:

  • Fade out current spotlight
  • Move spotlight to new target with animation
  • Fade in new tooltip

Conditional steps

Some steps depend on user state:

  • Skip “create project” step if user already has a project
  • Show “billing” step only for paid users

Tour engine evaluates step preconditions before showing.

Action steps

Some tours require user action to proceed:

  • “Click the New button to continue”
  • Tour waits for the click
  • Then advances to next step

Implementation: attach a one-time click listener; advance when triggered.

Some tours span multiple pages:

  • Step on /dashboard
  • Click button → navigate to /settings
  • Tour resumes on /settings page

Persist tour state in URL or localStorage so it survives navigation.

Skip and persistence

  • Skip button: marks tour complete
  • Complete state stored in user profile (server) or localStorage
  • Tour does not re-trigger
  • Optionally: “Replay tour” in help menu

Multiple tours

Different tours for different features:

  • Onboarding tour (first run)
  • “What’s new” after major release
  • Per-feature tours (advanced features)

Each tour has its own ID and persisted state.

Mobile

Mobile tours need different UX:

  • Bottom sheet for tooltip (not floating popover)
  • Larger tap targets
  • Reduce step count (mobile attention is limited)

Common antipatterns

  • 10+ step tours (users abandon)
  • Tooltips that obscure the target they describe
  • No skip button
  • Re-triggering tour after completion
  • Targeting elements that may not be on the page

Library options

  • react-joyride: most popular React option
  • intro.js: framework-agnostic, mature
  • shepherd.js: theme-friendly, well-maintained
  • Userflow / Pendo / Intercom Tours: SaaS, no-code

Frequently Asked Questions

How long should a tour be?

3–7 steps. Beyond that, completion drops sharply. Show only the highest-value features; let users discover the rest.

What about progressive onboarding?

Some apps trigger contextual tours when the user encounters relevant features (Slack does this). More effective than one-shot tour at first run.

Should I use a SaaS tour product or build it?

SaaS products (Userflow, Appcues) let non-engineers create tours. Build it if you want full control or have unusual UX requirements.

Scroll to Top