This is a port of driver.js.
The code has been fully refactored and rewritten to TS. It uses a different highlight technique under the hood, which does not fiddle with z-index.
This ensures the layout will always stay intact. With driver.js this is not the case.
After more and more work on this port, there are more changes and improvements available. At the moment the documentation is not 100% updated, please bear with me until I get around to it.
For a full comparison you can check here.
Boarding.js
Powerful, highly customizable vanilla JavaScript engine to onboard your users to your page or application
No external dependencies, supports all major browsers and highly customizable
- 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
- 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 include it using CDN. If you want a specific version, put it as boarding.js@3.0.1
in the name
<script src="https://unpkg.com/boarding.js/dist/main.js"></script>
<link rel="stylesheet" href="https://unpkg.com/boarding.js/styles/main.css" />
<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";
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 prefferedSide
and the alignment
property.
const boarding = new Boarding();
boarding.highlight({
element: "#some-element",
popover: {
title: "Title for the Popover",
description: "Description for it",
prefferedSide: "left",
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",
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();
boarding.defineSteps([
{
element: "#first-element-introduction",
popover: {
className: "first-step-popover-class",
title: "Title on Popover",
description: "Body of the popover",
prefferedSide: "left",
},
},
{
element: "#second-element-introduction",
popover: {
title: "Title on Popover",
description: "Body of the popover",
prefferedSide: "top",
},
},
{
element: "#third-element-introduction",
popover: {
title: "Title on Popover",
description: "Body of the popover",
prefferedSide: "right",
},
},
]);
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();
boarding.defineSteps([
{
element: "#first-element-introduction",
popover: {
title: "Title on Popover",
description: "Body of the popover",
prefferedSide: "left",
},
},
{
element: "#second-element-introduction",
popover: {
title: "Title on Popover",
description: "Body of the popover",
prefferedSide: "top",
},
onNext: () => {
boarding.preventMove();
setTimeout(() => {
boarding.continue();
}, 4000);
},
},
{
element: "#third-element-introduction",
popover: {
title: "Title on Popover",
description: "Body of the popover",
prefferedSide: "right",
},
},
]);
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",
animate: true,
opacity: 0.75,
padding: 10,
allowClose: true,
overlayClickNext: false,
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) => {
},
});
Note that all the button options that you provide in the boarding definition can be overridden for a specific step by giving them in the step definition
Step Definition
Here is the set of options that you can pass while defining steps defineSteps
or the object that you pass to highlight
method:
const stepDefinition = {
element: "#some-item",
popover: {
className: "popover-class",
title: "Title",
description: "Description",
showButtons: false,
doneBtnText: "Done",
closeBtnText: "Close",
nextBtnText: "Next",
prevBtnText: "Previous",
preferredSide: "top",
alignment: "start",
onPopoverRender: (el) => {
},
},
prepareElement: () => {},
onNext: (Element) => {},
};
For example, here is how it would look when highlighting a single element:
const boarding = new Boarding(boardingOptions);
boarding.highlight(stepDefinition);
And this is how it would look when creating a step-by-step guide:
const boarding = new Boarding(boardingOptions);
boarding.defineSteps([
stepDefinition1,
stepDefinition2,
stepDefinition3,
stepDefinition4,
]);
API Methods
Below is the set of available methods:
const boarding = new Boarding(boardingOptions);
if (boarding.isActivated) {
console.log("Boarding is active");
}
boarding.defineSteps([stepDefinition1, stepDefinition2, stepDefinition3]);
boarding.start((stepNumber = 0));
boarding.next();
boarding.previous();
boarding.hasNextStep();
boarding.hasPreviousStep();
boarding.preventMove();
boarding.continue();
boarding.clearMovePrevented();
boarding.highlight(string | stepDefinition);
boarding.reset();
boarding.reset((clearImmediately = false));
if (boarding.hasHighlightedElement()) {
console.log("There is an element highlighted");
}
const activeElement = boarding.getHighlightedElement();
const lastActiveElement = boarding.getLastHighlightedElement();
Note – Do not forget to add e.stopPropagation()
to the click
binding that triggers boarding.
Contributions
Feel free to submit pull requests, create issues or spread the word.
License
MIT © Josias Ribi