- 
- Driver.js
-
- Light-weight, no-dependency, vanilla JavaScript engine to drive user's focus across - the - page
- - With Animation - Without Animation - - - --- -A 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.
-
What are the features?
-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.
--
-
- 🔆 Highlight any (literally any) item on page -
- ✋ Block user interactions -
- 📣 Create feature introductions -
- 👓 Add focus shifters for users -
- 🛠️ Highly customizable – Use it anywhere for overlay -
- ⌨️ User Friendly – Controllable by keys -
- 🆓 MIT Licensed – Free for personal and commercial use -
- 🕊️ Lightweight – Only ~4kb when gzipped -
- 🌀 Consistent behavior across all major browsers -
-
How does it do that?
-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.
--
Can you show some Examples?
-Below you find some of the examples and sample use-cases on how you can use it.
-Highlighting a Single Element – Without Popover
-If all you want is just highlight a single element, you can do that simply by passing the - selector
- Show Demo -const 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.
- -- -
Highlighting a Single Element – With Popover
-If you would like to show some details alongside the highlighted element, you can do that easily by specifying - title and description
- Show Demo -const 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.
-- -
Popover Positioning
-You can also, change the position of the popover to be either left, left-center, left-bottom, top, top-center, top-right,
- right, right-center, right-bottom or bottom, bottom-center, bottom-right, mid-center.
const driver = new Driver();
-driver.highlight({
- element: '#some-element',
- popover: {
- title: 'Title for the Popover',
- description: 'Description for it',
- // position can be left, left-center, left-bottom, top,
- // top-center, top-right, right, right-center, right-bottom,
- // bottom, bottom-center, bottom-right, mid-center
- position: 'left',
- }
-});
-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
-
HTML in Popovers
-You can also specify HTML in the body or the title of the popovers. Here is an example:
- Show Demo -const 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.
- --
Disable Close on Outside Click
-By default, driver.js gets reset if user clicks outside the highlighted element, you can disable this:
- Show Demo -const driver = new Driver({
- allowClose: false,
-});
-
-driver.highlight({
- element: '#some-element',
- popover: {
- title: '<em>An italicized title</em>',
- description: 'Description may also contain <strong>HTML</strong>'
- }
-});
-- If you use this option, for multi-step driver, it would close after you are done with the popover or you can close it programmatically. For single element popover, you need to close it properly, otherwise it won't be closed -
-driver.reset()
- -
Creating Feature Introductions
-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 Demo -const driver = new Driver();
-// Define the steps for introduction
-driver.defineSteps([
- {
- element: '#first-element-introduction',
- popover: {
- className: 'first-step-popover-class',
- 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.
- -- -
Without Overlay
-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 Demo -const 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
-- -
..and much much more
-Driver comes with many options that you can manipulate to make driver behave as you may like
-Driver Definition
-Here are the options that Driver understands
-const driver = new Driver({
- className: 'scoped-class', // className to wrap driver.js popover
- 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
- allowClose: true, // Whether clicking on overlay should close or not
- overlayClickNext: false, // Should it move to next step on overlay click
- 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 move)
- scrollIntoViewOptions: {}, // We use `scrollIntoView()` when possible, pass here the options for it if you want any
- 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
- onReset: (Element) {}, // Called when overlay is about to be cleared
- onNext: (Element) => {}, // Called when moving to next step on any step
- onPrevious: (Element) => {}, // Called when moving to next step on any step
-});
-Note that all the button options that you provide in the driver definition can be overridden for a - specific step by giving them in the step definition
-Step Definition
-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 string or Node to be highlighted
- popover: { // There will be no popover if empty or not given
- className: 'popover-class', // className to wrap this specific step popover in addition to the general className in Driver options
- title: 'Title', // Title on the popover
- description: 'Description', // Body of the popover
- showButtons: false, // Do not show control buttons in footer
- 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
- }
-};
-API Methods
-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
-
-// Prevents the current move. Useful in `onNext` or `onPrevious` if you want to
-// perform some asynchronous task and manually move to next step
-driver.preventMove();
-
-// Gets the currently highlighted element on screen
-const activeElement = driver.getHighlightedElement();
-const lastActiveElement = driver.getLastHighlightedElement();
-activeElement.getCalculatedPosition(); // 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
--
Contributing
-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 journey introduction - and overlays.
- Follow @kamranahmedse - - Follow -