Guided Tours

Guided tours for your application

Demo

Event Listeners

You can listen to all guided tour events to track user interactions and tour progress. Here's how to set up event listeners for all available events:

API

Tag

Name	Description
`<x-guided-tours>`	Custom Element, accepts tours configuration

Methods

Name	Description
`getGuidedTours()`	Returns a collection of all available guided tours in the application. This method returns a Promise that resolves to a `TourCollection` where each tour is accessible by its unique identifier.
`getGuidedTour(id: string)`	Retrieves a specific guided tour instance by providing its unique identifier. This method returns a Promise that resolves to a `TourInterface` object which can be used to control and interact with the tour.
`startGuidedTour(id: string)`	Initiates a specific guided tour by its unique identifier. If the tour has been completed or cancelled, it will not start again. For in-progress tours, resumes from the last viewed step. Use `restartGuidedTour()` to replay completed or cancelled tours. Returns a Promise that resolves when the tour has been started.
`restartGuidedTour(id: string)`	Clears the tour state and restarts the tour from the beginning. Use this method to allow users to replay completed or cancelled tours. Returns a Promise that resolves when the tour has been restarted.
`cancelGuidedTour(id: string)`	Cancels an active guided tour by its unique identifier. This method stops the tour sequence immediately and returns a Promise that resolves when the tour has been cancelled.
`completeGuidedTour(id: string)`	Marks a guided tour as completed by its unique identifier. This method ends the tour sequence and returns a Promise that resolves when the tour has been completed.

Properties

Name	Value	Required	Default	Description
`tours`	Array of objects of type `TourConfiguration`		`[]`	refer JSON Schema
`appkey`	string	Required when `userid` is provided	`undefined`	Application key used to namespace tour storage keys and prevent collisions between different applications. This value determines the localStorage key prefix (`x-guided-tours:appkey`) where tour state is persisted. Note: Required when `userid` is provided for state tracking. Component initialization will throw an error if `userid` is set without `appkey`. Choose a stable, unique identifier for your application (e.g., "returns-app", "compliance-dashboard").
`userid`	string	Required when `autoresume` is enabled	`undefined`	Unique identifier for the user. Required for tour state tracking, persistence, and autoresume functionality. When provided, tour progress is saved in localStorage per user. Note: Must be provided when `autoresume` is enabled, otherwise component initialization will throw an error.
`autoresume`	boolean		`undefined`	Automatically resume in-progress tours when the page loads. Requires `userid` to be set. When enabled, tours will automatically continue from where the user left off after a page refresh. Component will throw an error during initialization if `autoresume` is enabled without providing `userid`.

User State Tracking & Auto-Resume

The x-guided-tours component supports user-specific tour state tracking and automatic resume functionality.

Important: The userid prop is required when autoresume is enabled. The component will throw an error during initialization if autoresume="true" is set without providing a userid.

Basic Usage

How It Works

State Tracking: When userid is provided, the component automatically tracks tour progress in localStorage per user

Auto-Resume: When autoresume="true" is set, in-progress tours automatically continue from where the user left off after a page refresh (requires userid)

Smart Behavior: Completed and cancelled tours won't auto-launch again when startGuidedTour() is called. Use restartGuidedTour() to allow users to replay these tours

localStorage State

Tour state is stored in localStorage with the following structure:

{ "x-guided-tours:skylab-docs:user-123": { "onboarding-tour": { "status": "in_progress", "currentStepId": "autoresume-tour-how-it-works" } } }

Example: Resume After Refresh

When you start the tour above and navigate through the steps, your progress is saved. Try these steps:

Click "Start tour" and advance to step 2 or 3

Refresh the page

The tour automatically resumes at the step you were on!

Open DevTools → Application → Local Storage to see x-guided-tours:skylab-docs:user-123

Without Auto-Resume

If you prefer manual control, omit the autoresume prop and call startGuidedTour() explicitly. The method will automatically resume from the last viewed step if the tour is in progress. For completed or cancelled tours, use restartGuidedTour() to allow users to replay them:

// Set up without autoresume (appkey still required) const guidedTours = document.getElementById('guided-tours-with-autoresume'); // Start or resume in-progress tour (blocks completed/cancelled tours) await guidedTours.startGuidedTour('onboarding-tour'); // Or restart a completed/cancelled tour await guidedTours.restartGuidedTour('onboarding-tour');

Providing Replay Controls

Important: Once a tour is completed, users cannot replay it unless your application provides explicit UI controls (like a "Help" menu, "Replay Tour" button, or settings option).

After a tour is completed and the page is refreshed, startGuidedTour() will be blocked. You must provide UI controls that call restartGuidedTour() to allow users to replay completed tours.

TourConfiguration

Tour

Each item in the tours array has the following shape:

Property	Type	Description
`id`	string	Unique ID for the tour
`stepDefaults`	TourStepDefaultsConfiguration	Default step settings
`visual`	VisualSettings	Overlay and visual settings
`exit`	ExitSettings	Exit behavior customization
`keyboard`	KeyboardSettings	Enable/disable keyboard shortcuts
`steps`	TourStepConfiguration[]	Array of step configurations

Visual Settings

Adds a dimmed background behind highlighted targets.

"visual": { "enableHighlightOverlay": true }

Exit Behavior

Prompts user before exiting a tour.

"exit": { "requireConfirmation": true, "confirmationMessage": "Are you sure you want to exit the tour?" }

Keyboard Settings

Enables or disables keyboard shortcuts for navigation.

"keyboard": { "allowArrowKeys": true, "allowEscapeKey": true }

Step

Each step defines a single point in the guided tour:

Property	Type	Description
`id`	string	Unique ID for the step
`content`	{ title?, body? }	Title and body text shown in tooltip
`target`	{ selector?, placement? }	CSS selector and optional placement
`highlight`	HighlightSettings	Customize highlight styling
`container`	StepContainerSettings	Arrow and offset settings
`navigation`	TourStepNavigation	Buttons like Next, Back, Exit
`behavior`	TourStepBehavior	Scrolling and wait conditions
`showProgressIndicator`	boolean	Whether to show the progress indicator (current step number and total steps in the footer)

Navigation

You can configure buttons per step or as defaults:

"navigation": { "buttons": [ { "text": "Next", "tourActions": [{ "type": "next" }] }, { "text": "Back", "tourActions": [{ "type": "back" }], "secondary": true } ], "cancelIcon": { "enabled": true } }

Action Types

next, back, complete, cancel

show, removeStep, addStep, addSteps

domEvent (e.g., simulate click)

AI-Powered Tour Configuration

Need help creating your tour configuration? Use our AI-powered Guided Tour Configuration Assistant!

Note: This feature requires an Avalara ChatGPT license. If you don't have access, please request one through ServiceNow.

The assistant can help you:

Generate schema-compliant tour configurations without writing JSON manually

Collect all required inputs interactively, guiding you step-by-step through id, stepDefaults, steps, and advanced options

Support advanced features like dynamic DOM event triggers, step injection/removal, and scroll/wait behaviors

Eliminate manual errors by producing clean, valid JSON aligned to the x-guided-tour schema

Easily update or extend existing configurations with contextual guidance and validation

Speed up tour creation and testing with intelligent prompts and auto-completion for nested fields and enum values

Open Guided Tour Assistant

Demo

API

Tag

Name	Description
`<XGuidedTours>`	Accepts required tours configuration prop.

Methods

Name	Description
`getGuidedTours()`	Returns a collection of all available guided tours in the application. This method returns a Promise that resolves to a `TourCollection` where each tour is accessible by its unique identifier. See the React implementation notes below for more information on calling this method.
`getGuidedTour(id: string)`	Retrieves a specific guided tour instance by providing its unique identifier. This method returns a Promise that resolves to a `TourInterface` object which can be used to control and interact with the tour. See the React implementation notes below for more information on calling this method.
`startGuidedTour(id: string)`	Initiates a specific guided tour by its unique identifier. If the tour has been completed or cancelled, it will not start again. For in-progress tours, resumes from the last viewed step. Use `restartGuidedTour()` to replay completed or cancelled tours. This method returns a Promise that resolves when the tour has been started. See the React implementation notes below for more information on calling this method.
`restartGuidedTour(id: string)`	Clears the tour state and restarts the tour from the beginning. Use this method to allow users to replay completed or cancelled tours. This method returns a Promise that resolves when the tour has been restarted. See the React implementation notes below for more information on calling this method.
`cancelGuidedTour(id: string)`	Cancels an active guided tour by its unique identifier. This method stops the tour sequence immediately and returns a Promise that resolves when the tour has been cancelled. See the React implementation notes below for more information on calling this method.
`completeGuidedTour(id: string)`	Marks a guided tour as completed by its unique identifier. This method ends the tour sequence and returns a Promise that resolves when the tour has been completed. See the React implementation notes below for more information on calling this method.

Props

Name	Value	Required	Default	Description
`tours`	Array of objects of type `TourConfiguration`		`[]`	refer JSON Schema
`appKey`	string	Required when `userId` is provided	`undefined`	Application key used to namespace tour storage keys and prevent collisions between different applications. This value determines the localStorage key prefix (`x-guided-tours:appKey`) where tour state is persisted. Note: Required when `userId` is provided for state tracking. Component initialization will throw an error if `userId` is set without `appKey`. Choose a stable, unique identifier for your application (e.g., "returns-app", "compliance-dashboard").
`userId`	string	Required when `autoResume` is enabled	`undefined`	Unique identifier for the user. Required for tour state tracking, persistence, and auto-resume functionality. When provided, tour progress is saved in localStorage per user. Note: Must be provided when `autoResume` is enabled, otherwise component initialization will throw an error.
`autoResume`	boolean		`undefined`	Automatically resume in-progress tours when the page loads. Requires `userId` to be set. When enabled, tours will automatically continue from where the user left off after a page refresh. Component will throw an error during initialization if `autoResume` is enabled without providing `userId`.

User State Tracking & Auto-Resume

The XGuidedTours component supports user-specific tour state tracking and automatic resume functionality in React applications.

Important: The userId prop is required when autoResume is enabled. The component will throw an error during initialization if autoResume={true} is set without providing a userId.

How It Works

State Tracking: When userId prop is provided, the component automatically tracks tour progress in localStorage per user

Auto-Resume: When autoResume={true} is set, in-progress tours automatically continue from where the user left off after a page refresh (requires userId)

Smart Behavior: Completed and cancelled tours won't auto-launch again when startGuidedTour() is called. Use restartGuidedTour() to allow users to replay these tours

localStorage State

Tour state is stored in localStorage with the following structure:

{ "x-guided-tours:returns-app:user-123": { "onboarding-tour": { "status": "in_progress", "currentStepId": "step-3" } } }

Without Auto-Resume

If you prefer manual control, omit the autoResume prop and call startGuidedTour() explicitly. The method will automatically resume from the last viewed step if the tour is in progress. For completed or cancelled tours, use restartGuidedTour() to allow users to replay them:

const toursRef = useRef(null); // Start or resume in-progress tour (blocks completed/cancelled tours) await toursRef.current.startGuidedTour('onboarding-tour'); // Or restart a completed/cancelled tour await toursRef.current.restartGuidedTour('onboarding-tour');

Providing Replay Controls in React

Important: Once a tour is completed, users cannot replay it unless your application provides explicit UI controls (like a "Help" menu, "Replay Tour" button, or settings option).

After a tour is completed and the page is refreshed, startGuidedTour() will be blocked. You must provide UI controls that call restartGuidedTour() to allow users to replay completed tours.

TourConfiguration

Tour

Each item in the tours array has the following shape:

Property	Type	Description
`id`	string	Unique ID for the tour
`stepDefaults`	TourStepDefaultsConfiguration	Default step settings
`visual`	VisualSettings	Overlay and visual settings
`exit`	ExitSettings	Exit behavior customization
`keyboard`	KeyboardSettings	Enable/disable keyboard shortcuts
`steps`	TourStepConfiguration[]	Array of step configurations

Visual Settings

Adds a dimmed background behind highlighted targets.

"visual": { "enableHighlightOverlay": true }

Exit Behavior

Prompts user before exiting a tour.

"exit": { "requireConfirmation": true, "confirmationMessage": "Are you sure you want to exit the tour?" }

Keyboard Settings

Enables or disables keyboard shortcuts for navigation.

"keyboard": { "allowArrowKeys": true, "allowEscapeKey": true }

Step

Each step defines a single point in the guided tour:

Property	Type	Description
`id`	string	Unique ID for the step
`content`	TourStepContent	Title and body text shown in tooltip
`target`	TargetElement	CSS selector and optional placement
`highlight`	HighlightSettings	Customize highlight styling
`container`	StepContainerSettings	Arrow and offset settings
`navigation`	TourStepNavigation	Buttons like Next, Back, Exit
`behavior`	TourStepBehavior	Scrolling and wait conditions
`showProgressIndicator`	boolean	Whether to show the progress indicator (current step number and total steps in the footer)

Navigation

You can configure buttons per step or as defaults:

"navigation": { "buttons": [ { "text": "Next", "tourActions": [{ "type": "next" }] }, { "text": "Back", "tourActions": [{ "type": "back" }], "secondary": true } ], "cancelIcon": { "enabled": true } }

Action Types

next, back, complete, cancel

show, removeStep, addStep, addSteps

domEvent (e.g., simulate click)

AI-Powered Tour Configuration

Need help creating your tour configuration? Use our AI-powered Guided Tour Configuration Assistant!

Note: This feature requires an Avalara ChatGPT license. If you don't have access, please request one through ServiceNow.

The assistant can help you:

Generate schema-compliant tour configurations without writing JSON manually

Collect all required inputs interactively, guiding you step-by-step through id, stepDefaults, steps, and advanced options

Support advanced features like dynamic DOM event triggers, step injection/removal, and scroll/wait behaviors

Eliminate manual errors by producing clean, valid JSON aligned to the x-guided-tour schema

Easily update or extend existing configurations with contextual guidance and validation

Speed up tour creation and testing with intelligent prompts and auto-completion for nested fields and enum values

Open Guided Tour Assistant

React implementation notes

Using refs to call getGuidedTours and getGuidedTour method

In order to call the getGuidedTours() and getGuidedTour() method, you must create a ref, assign it to the XGuidedTours, and then use ref.current to access the method:

    
    import tours from './tours';
    
    // implementation in your component
    const guidedToursRef = React.createRef(); 
    
    async function getGuidedTours(): Promise<{ [key: string]: TourInterface }> {
      const tours = await guidedToursRef.current.getGuidedTours();
      return tours;
    }
    
    async function getGuidedTour(id: string): Promise<TourInterface> {
      const tour = await guidedToursRef.current.getGuidedTour(id);
      return tour;
    }
    
    return <XGuidedTours tours={tours} ref={guidedToursRef} />

Skylab React links

General information about using our React package

Typescript

Exported types

// Collection of tours indexed by tour ID export type TourCollection = Record<string, TourInterface>; // Interface for tour object export interface TourInterface { start(): void; next(): void; back(): void; cancel(): void; complete(): void; hide(): void; show(stepId: string): void; getCurrentStepId(): string | null; isActive(): boolean; removeStep(stepId: string): void; addStep(stepConfig: TourStepConfiguration): void; addSteps(stepConfigs: ReadonlyArray<TourStepConfiguration>): void; on(event: string, handler: () => void): void; off(event: string, handler: () => void): void; } // Main tour configuration export interface TourConfiguration { readonly id: string; readonly steps?: ReadonlyArray<TourStepConfiguration>; readonly stepDefaults?: TourStepDefaultsConfiguration; readonly keyboard?: KeyboardNavigation; readonly exit?: ExitSettings; readonly visual?: VisualSettings; } // Step configuration export interface TourStepConfiguration { readonly id: string; readonly content?: TourStepContent; readonly target?: TargetElement; readonly container?: StepContainerSettings; readonly highlight?: HighlightSettings; readonly navigation?: TourStepNavigation; readonly behavior?: TourStepBehavior; readonly showProgressIndicator?: boolean; } // Step defaults (TourStepConfiguration without 'id') export type TourStepDefaultsConfiguration = Omit<TourStepConfiguration, 'id'>; // Step content export interface TourStepContent { readonly title?: string; readonly body?: string; } // Target element configuration export interface TargetElement { readonly selector?: string; readonly placement?: Placement; } // Container settings export interface StepContainerSettings { readonly arrow?: boolean | CustomArrowImageOptions; readonly offset?: OffsetValue; } // Custom arrow image options export interface CustomArrowImageOptions { readonly src: string; readonly alt?: string; readonly width?: number; readonly height?: number; readonly offset?: OffsetValue; readonly placementToTarget?: Exclude<Placement, Placement.Auto | Placement.AutoStart | Placement.AutoEnd>; } // Offset value type type OffsetValue = | number | { readonly mainAxis?: number; readonly crossAxis?: number; readonly alignmentAxis?: number | null; }; // Highlight settings export interface HighlightSettings { readonly additionalHighlightSelectors?: ReadonlyArray<string>; readonly xOffset?: number; readonly yOffset?: number; readonly padding?: number; readonly borderRadius?: number | BorderRadiusConfig; } // Border radius configuration export type BorderRadiusConfig = { readonly topLeft?: number; readonly bottomLeft?: number; readonly bottomRight?: number; readonly topRight?: number; }; // Navigation configuration export interface TourStepNavigation { readonly buttons?: ReadonlyArray<StepOptionsButton>; readonly cancelIcon?: CancelIcon; readonly progressTrigger?: StepProgressTrigger; } // Button configuration export interface StepOptionsButton { readonly tourActions?: ReadonlyArray<TourAction>; readonly text?: string; readonly ariaLabel?: string; readonly disabled?: boolean; readonly secondary?: boolean; readonly classes?: string; } // Cancel icon configuration export interface CancelIcon { readonly enabled?: boolean; readonly ariaLabel?: string; } // Progress trigger export interface StepProgressTrigger { readonly event: string; readonly selector: string; } // Tour action types export type TourAction = | TourActionBasic | TourActionShow | TourActionRemoveStep | TourActionAddStep | TourActionAddSteps | TourActionDomEvent; export interface TourActionBasic { readonly type: Exclude<TourActionType, TourActionType.Show | TourActionType.AddStep | TourActionType.AddSteps | TourActionType.RemoveStep | TourActionType.DomEvent>; } export interface TourActionShow { readonly type: TourActionType.Show; readonly stepId: string; } export interface TourActionRemoveStep { readonly type: TourActionType.RemoveStep; readonly stepId: string; } export interface TourActionAddStep { readonly type: TourActionType.AddStep; readonly stepConfig: TourStepConfiguration; } export interface TourActionAddSteps { readonly type: TourActionType.AddSteps; readonly stepConfigs: ReadonlyArray<TourStepConfiguration>; } export interface TourActionDomEvent { readonly type: TourActionType.DomEvent; readonly selector: string; readonly eventName: keyof HTMLElementEventMap | GuidedTourMethods; readonly args?: unknown[]; } // Behavior configuration export interface TourStepBehavior { readonly waitForElementConditions?: WaitForElementConditions; readonly scrollToTarget?: boolean | ScrollIntoViewOptions; } // Wait for element conditions export interface WaitForElementConditions { readonly waitTimeout?: number; readonly skipStepIfTargetMissing?: boolean; } // Keyboard navigation export interface KeyboardNavigation { readonly allowArrowKeys?: boolean; readonly allowEscapeKey?: boolean; } // Exit settings export interface ExitSettings { readonly requireConfirmation?: boolean; readonly confirmationMessage?: string; } // Visual settings export interface VisualSettings { readonly enableHighlightOverlay?: boolean; }

Guidelines

Usage

The Guided Tours component provides functionality for creating interactive guided tours in web applications.

Basic Implementation

To implement the Guided Tours component, you need to provide a tours prop, which accepts an array of TourConfiguration objects.

Accessing Tours

This component creates a xGuidedTours object of tour instances. The xGuidedTours object can be accessed by calling methods attached to XGuidedTours element in the DOM.

Available Tour Controls

Each tour instance provides the following control methods:

start() - Start a tour

next() - Advance to the next step

back() - Return to the previous step

cancel() - Stop the current tour

complete() - End the tour

hide() - Hide current step

show(stepId) - Display a specific step

getCurrentStepId() - Get current step id of the tour

isActive() - Get if the tour is active

removeStep(stepId) - Remove a specific step

addStep(stepConfig) - Add a specific step

addSteps(stepConfigs) - Add specific steps

on(event, handler) - Register an event listener

off(event, handler) - Remove an event listener

Custom Arrow Configuration

The guided tours component supports custom arrow images that can replace the default CSS arrow pointer. This allows you to use branded or themed arrows that match your application's design.

Basic Configuration

To use a custom arrow, provide a CustomArrowImageOptions object to the container.arrow property:

{ id: "my-step", target: { selector: "#my-element", placement: "bottom" // Required for arrow to display }, container: { arrow: { src: "/path/to/arrow-image.svg", alt: "Custom arrow", width: 24, height: 24 } }, content: { title: "Step Title", body: "Step content" } }

Required Properties

Property	Type	Description
`src`	string	Required. The URL or path to the arrow image file. Supports relative and absolute URLs. Common formats: PNG, SVG, JPG, GIF.

Optional Properties

Property	Type	Description
`alt`	string	Alternative text for accessibility. Used by screen readers.
`width`	number	Width of the arrow in pixels. Recommended to avoid layout shifts.
`height`	number	Height of the arrow in pixels. Recommended to avoid layout shifts.
`offset`	number \| OffsetValue	Distance between the arrow and its target. Can be a simple number for uniform offset, or an object with `mainAxis`, `crossAxis`, and `alignmentAxis` for fine-tuned positioning.
`placementToTarget`	Placement	Explicit placement of the arrow relative to the target element. Overrides automatic placement calculation. Values: `top`, `right`, `bottom`, `left`, `top-start`, `top-end`, `bottom-start`, `bottom-end`, `left-start`, `left-end`, `right-start`, `right-end`.

Advanced Example with Offset and Placement

{ id: "advanced-step", target: { selector: "#target-element", placement: "bottom" }, container: { arrow: { src: "https://example.com/custom-arrow.svg", alt: "Navigation arrow", width: 32, height: 32, placementToTarget: "top-start", offset: { mainAxis: 10, // 10px from target crossAxis: 5 // 5px horizontal shift } } } }

Important Notes

Target placement required: The target.placement property must be set for Shepherd to create the arrow container element.
Image format: Use SVG for scalable arrows that look crisp at any size.
Dimensions: Specify both width and height to avoid layout shifts during image loading.
Accessibility: Always include meaningful alt text for screen readers.
Performance: Optimize images to minimize load time and improve user experience.

How It Works

When a custom arrow is configured:

Shepherd.js creates the default arrow container element (.shepherd-arrow)
The custom arrow callback adds the shepherd-arrow-custom-container class to hide the default triangle
A new <img> element is created with class shepherd-arrow-custom
The image element replaces the content inside the arrow container
The image is positioned immediately using Floating UI based on the configuration
A MutationObserver tracks placement changes to reposition the arrow dynamically when the step container moves

Design

Design resources can be found on the Skylab design documentation site: skylab.avalara.com