A light-weight, no-dependency, vanilla JavaScript engine to drive the user's focus across the page
Quick TourA lightweight (~4kb gzipped) yet powerful JavaScript engine that helps you drive the user's focus on page.
Some sample use-cases can be creating powerful feature introductions, call-to-action components, focus shifters etc.
Driver is compatible with all the major browsers and can be used for any of your overlay needs. Feature introductions, focus shifters, call-to-action are just a few examples.
In it simplest, it puts the canvas on top of the whole page and then cuts the part that is over the element to be highlighted and provides you several hooks when highlighting, highlighted or un-highlighting elements making it highly customizable.
Below you find some of the examples and sample use-cases on how you can use it. Run by clicking the
RUN
button.
If all you want is just highlight a single element, you can do that simply by passing the selector
Show Democonst driver = new Driver();
driver.highlight('#create-post');
A real world use-case for this could be highlighting an element when user is interacting with it
const focusDriver = new Driver();
// Highlight the section on focus
document.getElementById('creation-input')
.addEventListener('focus', (e) => {
focusDriver.focus('#creation-input');
});
Focus any of the inputs and see how it moves the highlight from one element to the other
You can also turn off the animation or set the padding around the corner. More on it later.
If you would like to show some details alongside the highlighted element, you can do that easily by specifying title and description
Show Democonst driver = new Driver();
driver.highlight({
element: '#some-element',
popover: {
title: 'Title for the Popover',
description: 'Description for it',
}
});
You can modify the behavior of this popover also by a certain set of options. More on it below.
You can also, change the position of the popover to be either left
, top
,
right
or bottom
.
const driver = new Driver();
driver.highlight({
element: '#some-element',
popover: {
title: 'Title for the Popover',
description: 'Description for it',
position: 'left', // can be `top`, `left`, `right`, `bottom`
}
});
If you don't specify the position or specify it to be auto
, it will
automatically
find the suitable position for the popover and show it
You can also specify HTML in the body or the title of the popovers. Here is an example:
Show Democonst driver = new Driver();
driver.highlight({
element: '#some-element',
popover: {
title: '<em>An italicized title</em>',
description: 'Description may also contain <strong>HTML</strong>'
}
});
And of-course it can be any valid HTML.
You can also make powerful feature introductions to guide the users about the features. Just provide an array of steps where each step specifies an element to highlight.
Below is just a quick example showing you how to combine the steps in introduction.
Show Democonst driver = new Driver();
// Define the steps for introduction
driver.defineSteps([
{
element: '#first-element-introduction',
popover: {
title: 'Title on Popover',
description: 'Body of the popover',
position: 'left'
}
},
{
element: '#second-element-introduction',
popover: {
title: 'Title on Popover',
description: 'Body of the popover',
position: 'top'
}
},
{
element: '#third-element-introduction',
popover: {
title: 'Title on Popover',
description: 'Body of the popover',
position: 'right'
}
},
]);
// Start the introduction
driver.start();
This is just a quick example for the feature introduction. For a richer one, please have a look at the "Quick Tour"
You may also turn off the footer buttons in popover, in which case user can control the popover using the arrows keys on keyboard. Or you may control it using the methods provided by Driver.
You can create feature introductions and do everything listed above without overlays also. All you have to do is just set the opacity to `0`.
Show Democonst driver = new Driver({
opacity: 0,
});
driver.highlight({
element: '#run-element-without-popover',
popover: {
title: 'Title for the Popover',
description: 'Description for it',
position: 'top', // can be `top`, `left`, `right`, `bottom`
}
});
..and you can do the same for the feature introductions
Driver comes with many options that you can manipulate to make driver behave as you may like
Here are the options that Driver understands
const driver = new Driver({
animate: true, // Animate while changing highlighted element
opacity: 0.75, // Background opacity (0 means only popovers and without overlay)
padding: 10, // Distance of element from around the edges
onHighlightStarted: (Element) {}, // Called when element is about to be highlighted
onHighlighted: (Element) {}, // Called when element is fully highlighted
onDeselected: (Element) {}, // Called when element has been deselected
});
Here are the set of options that you can pass in each step i.e. an item in array of steps or the object
that
you pass to highlight
method
const stepDefinition = {
element: '#some-item', // Query selector for the item to be highlighted
popover: { // There will be no popover if empty or not given
title: 'Title', // Title on the popover
description: 'Description', // Body of the popover
showButtons: false, // Do not show control buttons in footer
doneBtnText: 'Done', // Text on the last button
closeBtnText: 'Close', // Text on the close button
nextBtnText: 'Next', // Next button text
prevBtnText: 'Previous', // Previous button text
}
};
Below are the set of methods that are available to you
const driver = new Driver(driverOptions);
const isActivated = driver.isActivated; // Checks if the driver is active or not
driver.moveNext(); // Moves to next step in the steps list
driver.movePrevious(); // Moves to previous step in the steps list
driver.start(stepNumber = 0); // Starts driving through the defined steps
driver.highlight(string|stepDefinition); // highlights the element using query selector or the step definition
driver.reset(); // Resets the overlay and clears the screen
driver.hasHighlightedElement(); // Checks if there is any highlighted element
driver.hasNextStep(); // Checks if there is next step to move to
driver.hasPreviousStep(); // Checks if there is previous step to move to
// Gets the currently highlighted element on screen
const activeElement = driver.getHighlightedElement();
const lastActiveElement = driver.getLastHighlightedElement();
activeElement.getScreenCoordinates(); // Gets screen co-ordinates of the active element
activeElement.hidePopover(); // Hide the popover
activeElement.showPopover(); // Show the popover
activeElement.getNode(); // Gets the DOM Element behind this element
You can use a variety of options to achieve whatever you may want. I have some plans on improving it further, make sure to keep an eye on the github page
You can find the contribution instructions on the github page. Feel free to submit an issue, create a pull request or spread the word
A product by Kamran produced out of boredom and frustration after he gave up on trying to find a perfect solution to integrate feature introductions and overlays.