Boarding.js

If you need to perform an asynchronous action (like waiting for an element to mount or an animation to finish) before moving to the next step, use the onNext or onPrevious callbacks.

1. Call boarding.preventMove() inside the callback to halt the transition.
2. Perform your async task.
3. Call boarding.continue() to resume the tour transition.

const boarding = new Boarding();

boarding.defineSteps([
  {
    element: "#first-element-introduction",
    popover: {
      title: "Title on Popover",
      description: "Body of the popover",
      preferredSide: "left",
    },
  },
  {
    element: "#second-element-introduction",
    popover: {
      title: "Title on Popover",
      description: "Body of the popover",
      preferredSide: "top",
    },
    onNext: () => {
      // Prevent moving to the next step
      boarding.preventMove();

      // Perform some action or create the element to move to
      // And then move to that element
      setTimeout(() => {
        boarding.continue();
      }, 4000);
    },
  },
  {
    element: "#third-element-introduction",
    popover: {
      title: "Title on Popover",
      description: "Body of the popover",
      preferredSide: "right",
    },
  },
]);

boarding.start();

To create a guided tour or feature introduction, use defineSteps() to register an array of step objects, then call start() to begin the tour. Each step defines an element to highlight and an optional popover containing information.

const boarding = new Boarding();

// Define the steps for introduction
boarding.defineSteps([
  {
    element: "#first-element-introduction",
    popover: {
      className: "first-step-popover-class",
      title: "Title on Popover",
      description: "Body of the popover",
      preferredSide: "left",
    },
  },
  {
    element: "#second-element-introduction",
    popover: {
      title: "Title on Popover",
      description: "Body of the popover",
      preferredSide: "top",
    },
  },
  {
    element: "#third-element-introduction",
    popover: {
      title: "Title on Popover",
      description: "Body of the popover",
      preferredSide: "right",
    },
  },
]);

// Start the introduction
boarding.start();

A step definition describes what element to highlight and what content to show in the popover. You can pass a step definition directly to highlight() for a single-element tour, or use them within defineSteps() to create a multi-step guide. Step-level options (like doneBtnText or onNext) will override the global Boarding configuration.

const stepDefinition = {
  element: "#some-item", // Query selector string or Node to be highlighted
  popover: {
    className: "popover-class", // Additional className for this specific popover
    title: "Title", // Title on the popover
    description: "Description", // Body of the popover
    showButtons: false, // Do not show control buttons in footer
    doneBtnText: "Done",
    closeBtnText: "Close",
    nextBtnText: "Next",
    prevBtnText: "Previous",
    preferredSide: "top", // Preferred side for popover rendering
    alignment: "start", // Alignment on the preferred side
    onPopoverRender: (el) => {
      // Make changes to the actual popoverElements once they get rendered.
    },
  },
  prepareElement: () => {}, // Called *before* moving to this step
  onNext: (Element) => {}, // Overwrite original onX eventhandlers for this step
};

When initializing a new Boarding instance, you can provide a configuration object to define global behaviors such as animation, overlay appearance, button text, and lifecycle event handlers. These settings apply to all steps unless overridden in a specific step definition.

const boarding = new Boarding({
  className: "scoped-class", // className to wrap boarding.js popover
  animate: true, // Whether to animate or not
  opacity: 0.75, // Overlay opacity (0 means only popovers and without overlay)
  padding: 10, // Distance of element from around the edges
  allowClose: true, // Whether the click on overlay should close or not
  overlayClickNext: false, // Whether the click on overlay should move next
  overlayColor: "rgb(0,0,0)", // Fill color for the overlay
  doneBtnText: "Done", // Text on the final button
  closeBtnText: "Close", // Text to the close button for this step
  nextBtnText: "Next", // Next button text for this step
  prevBtnText: "Previous", // Previous button text for this step
  showButtons: false, // Do not show control buttons in footer
  keyboardControl: true, // Allow controlling through keyboard (escape to close, arrow keys to move)
  scrollIntoViewOptions: {
    behaviour: "smooth",
  }, // Options for scrollIntoView(). Set to "no-scroll" to disable.
  onBeforeHighlighted: (HighlightElement) => {},
  onHighlighted: (HighlightElement) => {},
  onDeselected: (HighlightElement) => {},
  onReset: (HighlightElement) => {},
  onStart: (HighlightElement) => {},
  onNext: (HighlightElement) => {},
  onPrevious: (HighlightElement) => {},
  strictClickHandling: true, // "block-all", true (isolate to highlighted element), or false
  onPopoverRender: (el) => {
    // Make changes to the actual popoverElements once they get rendered.
  },
});

To use Boarding.js, instantiate the Boarding class with an optional BoardingOptions object. This object allows you to configure global behaviors for the onboarding session, such as animation, overlay styling, and interaction rules.

Key configuration options include:

• strictClickHandling: Determines if only the highlighted element can be clicked. Values can be 'block-all' (blocks all clicks), a boolean (allows only the element), or undefined (default).
• animate: Boolean to enable/disable overlay animations.
• padding: Spacing around the highlighted element.
• radius: Rounded corners for the cutout.
• allowClose: Whether clicking outside the element or pressing Escape closes the session.
• overlayClickNext: Whether clicking outside the element triggers the next() action.
• keyboardControl: Enables/disables arrow key navigation.
• onReset: Callback triggered when the session ends.

import Boarding from './lib/boarding';

const boarding = new Boarding({
  strictClickHandling: 'block-all',
  animate: true,
  padding: 10,
  radius: 5,
  allowClose: true,
  overlayClickNext: false,
  onReset: (reason) => console.log('Session ended:', reason)
});