Driver.js

A light-weight, no-dependency, vanilla JavaScript engine to drive the user'...

Tour - Guide
kamranahmedse/driver.jskamranahmed.info/driver.jsdriver.js

README


Driver.js

version downloads

Powerful, highly customizable vanilla JavaScript engine to drive the user's focus across the page
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 browsers (including in-famous IE)
MIT Licensed: free for personal and commercial use

undefined

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. Driver.js can be used wherever you need some sort of overlay for the page; some common usecases could be: e.g. dimming the background when user is interacting with some component i.e. the way Facebook does when you try to create a post, using it as a focus shifter to bring user's attention to some component on page, or using it to simulate those "Turn off the Lights" widgets that you might have seen on video players online, etc.

Driver.js is written in Vanilla JS, 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.

  1. ```bash
  2. yarn add driver.js
  3. npm install driver.js
  4. ```
Or include it using CDN. If you want a specific version, put it as driver.js@0.5 in the name
  1. ```html
  2. <script src="https://unpkg.com/driver.js/dist/driver.min.js"></script>
  3. <link rel="stylesheet" href="https://unpkg.com/driver.js/dist/driver.min.css">
  4. ```

Or grab the code from dist directory and include it directly.

  1. ```html
  2. <link rel="stylesheet" href="/dist/driver.min.css">
  3. <script src="/dist/driver.min.js"></script>
  4. ```

undefined

Usage and Demo


If you are using some sort of module bundler, import the library and the CSS file

  1. ```javascript
  2. import Driver from 'driver.js';
  3. import 'driver.js/dist/driver.min.css';
  4. ```
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.

  1. ```javascript
  2. const driver = new Driver();
  3. driver.highlight('#create-post');
  4. ```
A real world usage example for this is: using it to dim the background and highlight the required element e.g. the way Facebook does it when creating a post.

Highlight and Popover – Demo


You can show additional details beside the highlighted element using the popover.

  1. ```javascript
  2. const driver = new Driver();
  3. driver.highlight({
  4.   element: '#some-element',
  5.   popover: {
  6.     title: 'Title for the Popover',
  7.     description: 'Description for it',
  8.   }
  9. });
  10. ```

Also, title and description can have HTML as well.

Positioning the Popover – Demo


By default, driver automatically finds the suitable position for the popover and displays it. You can override it using position property.

  1. ```javascript
  2. const driver = new Driver();
  3. driver.highlight({
  4.   element: '#some-element',
  5.   popover: {
  6.     title: 'Title for the Popover',
  7.     description: 'Description for it',
  8.     // position can be left, left-center, left-bottom, top,
  9.     // top-center, top-right, right, right-center, right-bottom,
  10.     // bottom, bottom-center, bottom-right, mid-center
  11.     position: 'left',
  12.   }
  13. });
  14. ```

You can also add offset to the popover position by using the offset property

  1. ```javascript
  2. const driver = new Driver();
  3. driver.highlight({
  4.   element: '#some-element',
  5.   popover: {
  6.     title: 'Title for the Popover',
  7.     description: 'Description for it',
  8.     position: 'bottom',
  9.     // Will show it 20 pixels away from the actual position of popover
  10.     // You may also provide the negative values
  11.     offset: 20,
  12.   }
  13. });
  14. ```

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 Driver. Define the steps and call the start when you want to start presenting. User will be able to control the steps using the keyboard or using the buttons on popovers.

  1. ```javascript
  2. const driver = new Driver();

  4. // Define the steps for introduction
  5. driver.defineSteps([
  6.   {
  7.     element: '#first-element-introduction',
  8.     popover: {
  9.       className: 'first-step-popover-class',
  10.       title: 'Title on Popover',
  11.       description: 'Body of the popover',
  12.       position: 'left'
  13.     }
  14.   },
  15.   {
  16.     element: '#second-element-introduction',
  17.     popover: {
  18.       title: 'Title on Popover',
  19.       description: 'Body of the popover',
  20.       position: 'top'
  21.     }
  22.   },
  23.   {
  24.     element: '#third-element-introduction',
  25.     popover: {
  26.       title: 'Title on Popover',
  27.       description: 'Body of the popover',
  28.       position: 'right'
  29.     }
  30.   },
  31. ]);

  33. // Start the introduction
  34. driver.start();
  35. ```
You can also hide the buttons and control the introductions programmatically by using the API methods listed below.

undefined

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 driver.preventMove() in your onNext or onPrevious callbacks and initiate it manually using driver.moveNext(). Here is a sample implementation where it will stop at the second step for four seconds and then move on to the next step.

  1. ```javascript
  2. const driver = new Driver();

  4. // Define the steps for introduction
  5. driver.defineSteps([
  6.   {
  7.     element: '#first-element-introduction',
  8.     popover: {
  9.       title: 'Title on Popover',
  10.       description: 'Body of the popover',
  11.       position: 'left'
  12.     }
  13.   },
  14.   {
  15.     element: '#second-element-introduction',
  16.     popover: {
  17.       title: 'Title on Popover',
  18.       description: 'Body of the popover',
  19.       position: 'top'
  20.     },
  21.     onNext: () => {
  22.       // Prevent moving to the next step
  23.       driver.preventMove();
  24.       
  25.       // Perform some action or create the element to move to
  26.       // And then move to that element
  27.       setTimeout(() => {
  28.         driver.moveNext();
  29.       }, 4000);
  30.     }
  31.   },
  32.   {
  33.     element: '#third-element-introduction',
  34.     popover: {
  35.       title: 'Title on Popover',
  36.       description: 'Body of the popover',
  37.       position: 'right'
  38.     }
  39.   },
  40. ]);

  42. // Start the introduction
  43. driver.start();
  44. ```
You can also hide the buttons and control the introductions programmatically by using the API methods listed below.

undefined

API


Driver comes with several options that you can manipulate to make Driver behave as you like

Driver Definition


Here are the options that Driver understands:

  1. ```javascript
  2. const driver = new Driver({
  3.   className: 'scoped-class',        // className to wrap driver.js popover
  4.   animate: true,                    // Whether to animate or not
  5.   opacity: 0.75,                    // Background opacity (0 means only popovers and without overlay)
  6.   padding: 10,                      // Distance of element from around the edges
  7.   allowClose: true,                 // Whether the click on overlay should close or not
  8.   overlayClickNext: false,          // Whether the click on overlay should move next
  9.   doneBtnText: 'Done',              // Text on the final button
  10.   closeBtnText: 'Close',            // Text on the close button for this step
  11.   stageBackground: '#ffffff',       // Background color for the staged behind highlighted element
  12.   nextBtnText: 'Next',              // Next button text for this step
  13.   prevBtnText: 'Previous',          // Previous button text for this step
  14.   showButtons: false,               // Do not show control buttons in footer
  15.   keyboardControl: true,            // Allow controlling through keyboard (escape to close, arrow keys to move)
  16.   scrollIntoViewOptions: {},        // We use `scrollIntoView()` when possible, pass here the options for it if you want any
  17.   onHighlightStarted: (Element) => {}, // Called when element is about to be highlighted
  18.   onHighlighted: (Element) => {},      // Called when element is fully highlighted
  19.   onDeselected: (Element) => {},       // Called when element has been deselected
  20.   onReset: (Element) => {},            // Called when overlay is about to be cleared
  21.   onNext: (Element) => {},                    // Called when moving to next step on any step
  22.   onPrevious: (Element) => {},                // Called when moving to previous step on any step
  23. });
  24. ```
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 while defining steps defineSteps or the object that you pass to highlight method:

  1. ```javascript
  2. const stepDefinition = {
  3.   element: '#some-item',        // Query selector string or Node to be highlighted
  4.   stageBackground: '#ffffff',   // This will override the one set in driver
  5.   popover: {                    // There will be no popover if empty or not given
  6.     className: 'popover-class', // className to wrap this specific step popover in addition to the general className in Driver options
  7.     title: 'Title',             // Title on the popover
  8.     description: 'Description', // Body of the popover
  9.     showButtons: false,         // Do not show control buttons in footer
  10.     doneBtnText: 'Done',        // Text on the last button
  11.     closeBtnText: 'Close',      // Text on the close button
  12.     nextBtnText: 'Next',        // Next button text
  13.     prevBtnText: 'Previous',    // Previous button text
  14.   },
  15.   onNext: () => {},             // Called when moving to next step from current step
  16.   onPrevious: () => {},         // Called when moving to previous step from current step
  17. };
  18. ```

For example, here is how it would look when highlighting a single element:

  1. ```javascript
  2. const driver = new Driver(driverOptions);
  3. driver.highlight(stepDefinition);
  4. ```

And this is how it would look when creating a step by step guide:

  1. ```javascript
  2. const driver = new Driver(driverOptions);
  3. driver.defineSteps([
  4.     stepDefinition1,
  5.     stepDefinition2,
  6.     stepDefinition3,
  7.     stepDefinition4,
  8. ]);
  9. ```

API Methods


Below are the set of methods that are available:

  1. ```javascript
  2. const driver = new Driver(driverOptions);

  4. // Checks if the driver is active or not
  5. if (driver.isActivated) {
  6.     console.log('Driver is active');
  7. }

  9. // In case of the steps guide, you can call below methods
  10. driver.defineSteps([ stepDefinition1, stepDefinition2, stepDefinition3 ]);
  11. driver.start(stepNumber = 0);  // Starts driving through the defined steps
  12. driver.moveNext();             // Moves to next step in the steps list
  13. driver.movePrevious();         // Moves to previous step in the steps list
  14. driver.hasNextStep();          // Checks if there is next step to move to
  15. driver.hasPreviousStep();      // Checks if there is previous step to move to

  17. // Prevents the current move. Useful in `onNext` or `onPrevious` if you want to
  18. // perform some asynchronous task and manually move to next step
  19. driver.preventMove();

  21. // Highlights the element using query selector or the step definition
  22. driver.highlight(string|stepDefinition);

  24. // Reposition the popover and highlighted element
  25. driver.refresh();

  27. // Resets the overlay and clears the screen
  28. driver.reset();

  30. // Additionally you can pass a boolean parameter
  31. // to clear immediately and not do the animations etc
  32. // Could be useful when you, let's say, want to run
  33. // a different instance of driver while one was running
  34. driver.reset(clearImmediately = false);

  36. // Checks if there is any highlighted element
  37. if(driver.hasHighlightedElement()) {
  38.     console.log('There is an element highlighted');
  39. }

  41. // Gets the currently highlighted element on screen
  42. // It would be an instance of `/src/core/element.js`
  43. const activeElement = driver.getHighlightedElement();

  45. // Gets the last highlighted element, would be an instance of `/src/core/element.js`
  46. const lastActiveElement = driver.getLastHighlightedElement();

  48. activeElement.getCalculatedPosition(); // Gets screen co-ordinates of the active element
  49. activeElement.hidePopover();           // Hide the popover
  50. activeElement.showPopover();           // Show the popover

  52. activeElement.getNode();  // Gets the DOM Element behind this element
  53. ```

undefined

Note – Do not forget to add e.stopPropagation() to the click binding that triggers driver.

undefined

Contributions


Feel free to submit pull requests, create issues or spread the word.

Sponsored By


Thanks to BrowserStack for sponsoring the compatibility testing needs.
BrowserStack

License


MIT © Kamran Ahmed