Guided Tours

Guided tours for your application

Demo

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. The tours are returned as a Promise that resolves to an object where each tour is accessible by its unique identifier.
`getGuidedTour(id: string)`	Retrieves a specific guided tour instance by providing its unique identifier. 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. This method starts the tour sequence and returns a Promise that resolves when the tour has been started. If the tour is not found, it logs an error to the console.
`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. If the tour is not found, it logs an error to the console.
`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. If the tour is not found, it logs an error to the console.

Properties

Name	Value	Required	Default	Description
`tours`	Array of objects of type `TourConfiguration`		`[]`	refer JSON Schema

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

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. The tours are returned as a Promise that resolves to an object 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. 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. This method starts the tour sequence and returns a Promise that resolves when the tour has been started. If the tour is not found, it logs an error to the console. 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. If the tour is not found, it logs an error to the console. 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. If the tour is not found, it logs an error to the console. 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

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

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 GuidedTours, 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 <GuidedTours tours={tours} ref={guidedToursRef} />

Skylab React links

General information about using our React package

Typescript

Exported types

// 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): void; } export interface TourStepConfiguration { readonly id: string; readonly content?: TourStepContent; readonly target?: TargetElement; readonly container?: StepContainerSettings; readonly highlight?: HighlightSettings; readonly navigation?: TourStepNavigation; readonly behavior?: TourStepBehavior; } export interface TourConfiguration { readonly id: string; readonly steps?: ReadonlyArray; readonly stepDefaults?: TourStepDefaultsConfiguration; readonly keyboard?: KeyboardNavigation; readonly exit?: ExitSettings; readonly visual?: VisualSettings; }

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

Design

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