Boarding.js
A light-weight, no-dependency, vanilla JavaScript engine to create powerful onboardings and drive the user's focus across the page
Install / Use
/learn @josias-r/Boarding.jsREADME
- Simple: is simple to use and has no external dependency at all
- Highly customizable: has a powerful API and can be used however you want
- Highlight anything: highlight any (literally any) element on page
- Feature introductions: create powerful feature introductions for your web applications
- Focus shifters: add focus shifters for users
- User friendly: Everything is controllable by keyboard
- Consistent behavior: usable across all major browsers
- Works with complex layouts: no z-index conflicts with your existing page elements
- Dynamic content support: define steps for elements not yet mounted (perfect for interactive SPAs like React applications)
- Auto popover positioning: automatically finds the best position for popovers with full control over alignment
- Flexible click handling: control allowed user interactions during tours with
strictClickHandling - Step preparation: validate and prepare moves before they happen with
prepareElement - Written in TypeScript: fully typed for better development experience
- MIT Licensed: free for personal and commercial use
For Usage and Examples, have a look at demo
So, yet another tour library?
No, it is not. Tours are just one of the many use-cases. Boarding.js can be used wherever you need some sort of overlay for the page; some common use cases could be: e.g. dimming the background when the user is interacting with some component, using it as a focus shifter to bring the user's attention to some component on a page (i.e. for a new feature introduction ✨), or using it to simulate those "Turn off the Lights 💡" widgets that you might have seen on video players online, etc.
Boarding.js is written in Vanilla JS (with TypeScript), has zero dependencies and is highly customizable. It has several options allowing you to manipulate how it behaves and also provides you the hooks to manipulate the elements as they are highlighted, about to be highlighted, or deselected.
Installation
You can install it using yarn or npm, whatever you prefer.
yarn add boarding.js
npm install boarding.js
Or import directly from a CDN. If you want a specific version, put it as boarding.js@3.5.2 in the name
<script type="module">
import { Boarding } from "https://unpkg.com/boarding.js/dist/main.js";
</script>
<link rel="stylesheet" href="https://unpkg.com/boarding.js/styles/main.css" />
<!-- optionally include the base theme -->
<link
rel="stylesheet"
href="https://unpkg.com/boarding.js/styles/themes/basic.css"
/>
Usage and Demo
If you are using some sort of module bundler, import the library and the CSS file
import { Boarding } from "boarding.js";
import "boarding.js/styles/main.css";
// optionally include the base theme
import "boarding.js/styles/themes/basic.css";
otherwise use the script and link tags to import the JavaScript and CSS files.
Demos and many more usage examples can be found in the docs page.
Highlighting Single Element – Demo
You can highlight a single element by simply passing the selector.
const boarding = new Boarding();
boarding.highlight("#create-post");
A real-world usage example for this is: using it to dim the background and highlight the required element e.g. when you want to introduce a new feature
Highlight and Popover – Demo
You can show additional details beside the highlighted element using the popover.
const boarding = new Boarding();
boarding.highlight({
element: "#some-element",
popover: {
title: "Title for the Popover",
description: "Description for it",
},
});
Also, title and description can have HTML as well.
Positioning the Popover – Demo
By default, boarding automatically finds the suitable position for the popover and displays it. You can override it using preferredSide and the alignment property (legacy prefferedSide is still supported).
const boarding = new Boarding();
boarding.highlight({
element: "#some-element",
popover: {
title: "Title for the Popover",
description: "Description for it",
// preferredSide can be left, right, top, bottom
preferredSide: "left",
// alignment can be start, center, right
alignment: "center",
},
});
You can also add offset to the popover position by using the offset property
const boarding = new Boarding();
boarding.highlight({
element: "#some-element",
popover: {
title: "Title for the Popover",
description: "Description for it",
// Will show it 20 pixels away from the actual position of popover
// You may also provide the negative values
offset: 20,
},
});
Creating Feature Introductions – Demo
Feature introductions are helpful when onboarding new users and giving them an idea about different parts of the application; you can create them seamlessly with Boarding. Define the steps and call the start when you want to start presenting. Users will be able to control the steps using the keyboard or using the buttons on popovers.
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();
You can also hide the buttons and control the introductions programmatically by using the API methods listed below.
Asynchronous Actions – Demo
For any asynchronous actions between the transition steps, you may delay the execution till the action completes. All you have to do is stop the transition using boarding.preventMove() in your onNext or onPrevious callbacks and then use boarding.continue() to continue the transition where you left off. Here is a sample implementation where it will stop at the second step for four seconds and then move on to the next step.
const boarding = new Boarding();
// Define the steps for introduction
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",
},
},
]);
// Start the introduction
boarding.start();
You can also hide the buttons and control the introductions programmatically by using the API methods listed below.
API
Boarding comes with several options that you can manipulate to make Boarding behave as you like
Boarding Definition
Here are the options that Boarding understands:
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 on 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
