Lightweight Vanilla JS Library for Interactive Guided Tours – Boarding.js

Boarding.js is a lightweight JavaScript library that highlights page elements to create guided tours with smooth animations.

It allows you to build step-by-step product introductions, dim the background to focus on specific UI elements.

Features:

• Zero Dependencies: Works with no external requirements.
• Dynamic Element Targeting: Defines steps for elements not yet mounted in the DOM, perfect for single-page applications built with React or Vue.
• Intelligent Popover Positioning: Automatically calculates optimal popover placement with manual override options for preferred side and alignment.
• Keyboard Navigation: You can control tours entirely through keyboard inputs for accessibility compliance.
• Strict Click Handling: Controls which page interactions are allowed during tours to prevent user confusion.
• Async Step Support: Validates and prepares elements before transitions using the prepareElement callback and preventMove API.
• TypeScript Support: Fully typed definitions improve development experience and catch errors at compile time.

See It In Action:

Use Cases:

• New Feature Rollouts: Introduce recently deployed features to existing users with contextual tours that explain functionality in place.
• User Onboarding Flows: Guide first-time users through application setup and core workflows with sequential step highlighting.
• Interactive Documentation: Create in-app tutorials that demonstrate features interactively.
• Focus Management: Direct user attention to specific UI elements during complex operations or form validation errors.

How To Use It:

1. Install Boarding.js with package managers.

# Yarn
$ yarn add boarding.js

# NPM
$ npm install boarding.js

2. Import the library and required CSS:

// Import the core library
import { Boarding } from "boarding.js";

// Import base styles required for overlay and positioning
import "boarding.js/styles/main.css";

// Optionally import the basic theme for styled popovers
import "boarding.js/styles/themes/basic.css";

3. For CDN usage without a build system:

<!-- Required base styles for overlay functionality -->
<link rel="stylesheet" href="https://unpkg.com/boarding.js/styles/main.css" />
<!-- Optional theme for default popover styling -->
<link rel="stylesheet" href="https://unpkg.com/boarding.js/styles/themes/basic.css" />

<script type="module">
  import { Boarding } from "https://unpkg.com/boarding.js/dist/main.js";
</script>

4. Highlight a single page element by passing its CSS selector. This works well for drawing attention to new features or guiding users to specific actions.

// Initialize Boarding instance
const boarding = new Boarding();

// Highlight element with ID "action"
boarding.highlight("#action");

5. Add descriptive content alongside highlighted elements:

boarding.highlight({
  element: "#cta",
  popover: {
    title: "CTA Title", // Accepts plain text or HTML
    description: "CTA Description", // Accepts plain text or HTML
  },
});

6. To create a multi-step guided tour, define an array of steps, and the library will take care of the rest.

Step Definition Options:

• element: string | Node – Query selector string or DOM Node to be highlighted.
• popover: object – Configuration for the popover (see below).
• prepareElement: () => {} – Called before moving to this step. Useful for setup logic.
• onNext: (Element) => {} – Overwrite the global onNext handler for this specific step.
• onPrevious: (Element) => {} – Overwrite the global onPrevious handler for this specific step.
• onHighlighted: (Element) => {} – Overwrite the global handler.
• onBeforeHighlighted: (Element) => {} – Overwrite the global handler.
• onDeselected: (Element) => {} – Overwrite the global handler.

Popover Object Properties:

• className: string – Additional class for this specific popover.
• title: string – Title text (supports HTML).
• description: string – Body text (supports HTML).
• showButtons: boolean – Toggle footer buttons for this step.
• doneBtnText: string – Custom text for the done button.
• closeBtnText: string – Custom text for the close button.
• nextBtnText: string – Custom text for the next button.
• prevBtnText: string – Custom text for the previous button.
• preferredSide: "top" | "right" | "bottom" | "left" – Preferred side to render the popover.
• alignment: "start" | "center" | "end" – Alignment of the popover relative to the side.
• offset: number – Pixel offset from the element.
• onPopoverRender: (el) => {} – Hook for direct DOM manipulation of the popover.

// Define array of step objects
boarding.defineSteps([
  {
    element: "#element-one",
    popover: {
      // Custom CSS class for styling this specific step
      className: "element-one",
      title: "Element 1",
      description: "Description 1",
      preferredSide: "left",
    },
  },
  {
    element: "#element-two",
    popover: {
      title: "Element 2",
      description: "Description 2",
      preferredSide: "top",
    },
    // OPTIONAL
    onNext: () => {
      // Stop automatic progression to next step
      boarding.preventMove();
      // Execute async operation (API call, animation, etc.)
      setTimeout(() => {
        // Resume tour after operation completes
        boarding.continue();
      }, 3000);
    },
  },
  {
    element: "#element-three",
    popover: {
      title: "Element 3",
      description: "Description 3",
      preferredSide: "right",
    },
  },
  // more steps here
]);

// Start the tour
boarding.start();

7. All configuration options.

• className: string – Class name to wrap the popover.
• animate: boolean – Whether to animate transitions. Default is true.
• opacity: number – Overlay opacity (0 means only popovers are visible without the dark overlay). Default is 0.75.
• padding: number – Distance of the highlight area from the element edges. Default is 10.
• allowClose: boolean – Whether clicking the overlay closes the tour. Default is true.
• overlayClickNext: boolean – Whether clicking the overlay moves to the next step. Default is false.
• overlayColor: string – Fill color for the overlay. Default is "rgb(0,0,0)".
• doneBtnText: string – Text on the final button. Default is "Done".
• closeBtnText: string – Text on the close button. Default is "Close".
• nextBtnText: string – Text on the next button. Default is "Next".
• prevBtnText: string – Text on the previous button. Default is "Previous".
• showButtons: boolean – Whether to show control buttons in the footer. Default is false.
• keyboardControl: boolean – Allow controlling through keyboard (Escape to close, Arrow keys to move). Default is true.
• scrollIntoViewOptions: object – Options passed to the native scrollIntoView(). Default includes { behaviour: "smooth" }. Set to "no-scroll" to disable.
• strictClickHandling: boolean | "block-all" – Controls pointer events. true allows clicks only on the highlighted element. "block-all" blocks all events.
• onBeforeHighlighted: (HighlightElement) => {} – Called when an element is about to be highlighted.
• onHighlighted: (HighlightElement) => {} – Called when an element is fully highlighted.
• onDeselected: (HighlightElement) => {} – Called when an element has been deselected.
• onReset: (HighlightElement) => {} – Called when the overlay is about to be cleared.
• onStart: (HighlightElement) => {} – Called when boarding.start() is triggered.
• onNext: (HighlightElement) => {} – Called when moving to the next step.
• onPrevious: (HighlightElement) => {} – Called when moving to the previous step.
• onPopoverRender: (el) => {} – Hook to manipulate popover elements after rendering.

const boarding = new Boarding({
  className: "scoped-class",
  animate: true,
  opacity: 0.75,
  padding: 10,
  allowClose: true,
  overlayClickNext: false, 
  overlayColor: "rgb(0,0,0)", 
  doneBtnText: "Done",
  closeBtnText: "Close",
  nextBtnText: "Next
  prevBtnText: "Previous", 
  showButtons: false,
  keyboardControl: true, 
  scrollIntoViewOptions: {
    behaviour: "smooth",
  }, 
  onBeforeHighlighted: (HighlightElement) => {},
  onHighlighted: (HighlightElement) => {},
  onDeselected: (HighlightElement) => {}, 
  onReset: (HighlightElement) => {}, 
  onStart: (HighlightElement) => {}, 
  onNext: (HighlightElement) => {}, 
  onPrevious: (HighlightElement) => {},
  strictClickHandling: true,
  onPopoverRender: (el) => {},
});

8. API methods.

• boarding.isActivated: Property. Checks if the boarding instance is currently active.
• boarding.defineSteps(steps): Defines the array of steps for the tour.
• boarding.start(stepNumber): Starts the tour at the specified index (default 0).
• boarding.next(): Moves to the next step.
• boarding.previous(): Moves to the previous step.
• boarding.hasNextStep(): Returns true if a next step exists.
• boarding.hasPreviousStep(): Returns true if a previous step exists.
• boarding.preventMove(): Pauses the transition. Use this inside event callbacks.
• boarding.continue(): Resumes a transition paused by preventMove.
• boarding.clearMovePrevented(): Clears the paused state without moving.
• boarding.highlight(string | stepDefinition): Highlights a specific element immediately.
• boarding.reset(clearImmediately): Clears the overlay and resets the instance. Pass true to skip animations.
• boarding.hasHighlightedElement(): Returns true if an element is currently highlighted.
• boarding.getHighlightedElement(): Returns the current HighlightElement instance.
• boarding.getLastHighlightedElement(): Returns the previously highlighted element.

Alternatives:

• Intro.js: A JS library with third-party themes. Larger file size than Boarding.js but includes more default styling options.
• Shepherd.js: Framework-agnostic tour library using Popper.js for positioning. More configuration complexity but offers fine-grained control over popover behavior.
• Driver.js: Lightweight alternative with similar API design. Fewer lifecycle hooks compared to Boarding.js but simpler for basic highlighting needs.

FAQs

Q: How do I prevent users from clicking elements outside the tour during onboarding?
A: Set the strictClickHandling option to true or “block-all” when initializing Boarding. The true setting allows clicks only on the highlighted element while “block-all” prevents all interactions except with the popover itself.

Q: Can I use Boarding.js with React or Vue single-page applications where elements mount asynchronously?
A: Yes. Define steps with selectors for elements that do not yet exist in the DOM. Boarding.js polls for these elements using MutationObserver and begins the step once they mount.

Q: What happens if a tour step targets an element that gets removed from the DOM during the tour?
A: The tour will skip that step automatically if the element no longer exists when Boarding tries to highlight it.

Q: How do I integrate Boarding.js with my existing analytics system to track tour completion rates?
A: Use the lifecycle callbacks to send tracking events. The onStart callback fires when a tour begins, onNext and onPrevious track navigation, and onReset indicates when users exit the tour early. You can also check hasNextStep in your onNext callback to identify the final step and track completions separately from early exits.

Q: Why does my popover appear in the wrong position on mobile devices?
A: Mobile browsers often have dynamic viewport heights due to address bars that hide on scroll. Ensure your scrollIntoViewOptions properly account for this by testing with different scroll positions. You can also increase the offset value to provide more breathing room between the element and popover on smaller screens.

The post Lightweight Vanilla JS Library for Interactive Guided Tours – Boarding.js appeared first on CSS Script.