repository·main·Indexed 20 days ago
https://github.com/sjmc11/tourguide-jsA customizable JavaScript library for creating user application onboarding tours. It features a TourGuideClient for managing tour lifecycles, support for defining steps via data attributes or TourGuideStep objects, and extensive configuration through TourGuideOptions for styling, scrolling, and navigation. The library includes built-in localStorage persistence to track tour completion.
To use TourGuide JS, you must import both the SCSS styles and the TourGuideClient class into your project.
// Style
import "@sjmc11/tourguidejs/src/scss/tour.scss"
// JS
import {TourGuideClient} from "@sjmc11/tourguidejs/src/Tour"You define the content of your tour steps by adding the data-tg-tour attribute to the HTML elements you want to highlight. The value of this attribute will be the text displayed in the tour guide step.
<div data-tg-tour="Welcome aboard 👋"> ... </div>Install the TourGuide JS package using npm to include it in your project.
npm i @sjmc11/tourguidejsTo implement a tour, instantiate a new TourGuideClient with your desired TourGuideOptions, then call the .start() method to begin the onboarding process.
// Create a tour
const tg = new TourGuideClient({} : TourGuideOptions)
// Start the tour
tg.start()The TourGuide class is the primary interface for managing tours. It maintains the state of the tour (visibility, active step, current group) and provides methods to control the tour lifecycle.
start(group?: string): Begins the tour. Optionally specify a group to filter steps.visitStep(stepIndex: "next" | "prev" | number): Navigates to a specific step or relative direction.nextStep() / prevStep(): Moves to the next or previous step.addSteps(newSteps: TourGuideStep): Dynamically adds new steps to the tour.exit(): Closes the active tour.setOptions(options: TourGuideOptions): Updates the tour configuration.finishTour(exit: boolean, tourGroup: string): Manually completes the tour.isVisible: Boolean indicating if the tour is currently active.activeStep: The index of the current step (0-based).isFinished: A getter that returns true if the current tour group has been completed (persisted in localStorage).// Example of interacting with the TourGuide instance
await tourGuide.start('onboarding');
await tourGuide.nextStep();
console.log(tourGuide.isVisible);When initializing a TourGuideClient, you can provide a TourGuideOptions object to customize the behavior, appearance, and navigation of the tour.
Key configuration categories include:
autoScroll: Enable/disable automatic scrolling to elements.autoScrollSmooth: Enable smooth scrolling transitions.autoScrollOffset: The pixel offset from the edge of the viewport for smooth scrolling.backdropColor: The color of the backdrop (supports RGBA only).backdropClass: CSS transition classes for the backdrop.backdropAnimate: Whether to animate the backdrop's position and size.targetPadding: The amount of space (in pixels) to leave around the highlighted target element.dialogClass: CSS class applied to the tour dialog.dialogZ: The z-index of the dialog.dialogWidth / dialogMaxWidth: Width and max-width style properties (recommended if your content includes images).dialogAnimate: Whether to animate the dialog's position and size.dialogPlacement: The placement of the dialog (uses Side or AlignedPlacement from @floating-ui/core).allowDialogOverlap: If true, allows the dialog to overlap the target element.nextLabel, prevLabel, finishLabel: Custom text for the navigation buttons.hideNext, hidePrev: Boolean flags to hide specific buttons.showButtons: Toggle visibility of next/prev buttons.showStepDots: Toggle visibility of progress dots.stepDotsPlacement: Position the dots in either the `const options: TourGuideOptions = {
autoScroll: true,
autoScrollSmooth: true,
backdropColor: 'rgba(0, 0, 0, 0.5)',
dialogWidth: 400,
nextLabel: 'Continue',
steps: [] // Array of TourGuideStep
};Use TourGuideOptions to customize the visual appearance and behavior of the tour.
Scrolling & Positioning
autoScroll: Automatically scroll to the target (default: true).autoScrollSmooth: Use smooth scrolling (default: true).autoScrollOffset: Offset from the edge during scroll (default: 20).targetPadding: Space around the highlighted target in px (default: 30).Visual Styling
backdropColor: RGBA string for the backdrop (default: "rgba(20,20,21,0.84)").backdropClass: Additional CSS class for the backdrop.dialogClass: Additional CSS class for the dialog.dialogWidth / dialogMaxWidth: Width controls for the dialog.dialogZ: Z-index of the dialog (default: 999).progressBar: Pass a color string to enable a progress bar under the header.Navigation & UI
nextLabel / prevLabel / finishLabel: Custom text for navigation buttons.showStepDots: Show progress dots (default: true).showStepProgress: Show human-readable progress like 1/5 (default: true).showButtons: Show next/prev buttons (default: true).hidePrev / hideNext: Hide specific navigation buttons.Behavior & Controls
exitOnEscape: Close tour on Escape key (default: true).exitOnClickOutside: Close tour when clicking the backdrop (default: true).keyboardControls: Enable arrow keys and Escape (default: false).completeOnFinish: If true, marks the tour group as finished in localStorage (default: true).rememberStep: Open the tour at the last active step (default: true).const options: TourGuideOptions = {
backdropColor: 'rgba(0, 0, 0, 0.5)',
nextLabel: 'Continue',
prevLabel: 'Go Back',
finishLabel: 'Got it!',
autoScrollSmooth: true,
completeOnFinish: true
};The client includes built-in support for tracking whether a tour has been completed using localStorage.
finishTour(groupKey): Marks the tour as complete for a specific group and exits. This is useful for ensuring users only see a tour once.isFinished: A property (function) that returns whether the current tour group has been completed.deleteFinishedTour(groupKeyOrAll): Removes the completion status from localStorage. Pass a specific group key or the string 'all' to clear all completed tours.// Mark a specific group as finished
tour.finishTour('onboarding-tour');
// Check if it was finished
if (tour.isFinished()) {
console.log('User has already seen this tour');
}
// Reset all finished tours
tour.deleteFinishedTour('all');To start using tourguide-js, instantiate the TourGuideClient class. You can optionally pass a TourGuideOptions object to the constructor to configure the tour's behavior. Upon instantiation, the client automatically creates the necessary DOM elements for the backdrop and the dialog.
import { TourGuideClient } from '@sjmc11/tourguidejs';
const tour = new TourGuideClient({
// options here
});Use setOptions(options) to update the TourGuideOptions of an existing client. This method will automatically refresh the dialog and backdrop to reflect the new configuration.
tour.setOptions({
debug: true
});The TourGuideClient provides several methods to control the flow of the tour once it has been initialized:
start(): Begins the tour by computing steps and initializing listeners.visitStep(stepIndexOrKeyword): Navigates to a specific step index or uses keywords like next or prev.nextStep(): Advances to the next step in the sequence (automatically calls finishTour() if it is the final step).prevStep(): Returns to the previous step.exit(): Closes the current tour.refresh(): Recomputes the entire tour, including all steps.refreshDialog(): Recomputes only the dialog content and the backdrop position.// Start the tour
tour.start();
// Navigate
tour.nextStep();
tour.prevStep();
tour.visitStep('next');
// Exit
tour.exit();You can hook into the tour's lifecycle to execute custom logic during transitions or exits. The following callback properties are available on the TourGuideClient instance:
| Callback | Trigger Timing |
|---|---|
onFinish | When the tour is successfully completed |
onBeforeExit | Just before the tour is closed/exited |
onAfterExit | After the tour has been closed |
onBeforeStepChange | Before moving from one step to another (receives currentStepIndex and stepIndex) |
onAfterStepChange | After a step change has occurred (receives previousStepIndex and stepIndex) |