{guide.data.title}
26 |Due to its extensive API, driver.js can be used for a wide range of use 5 | cases.
6 |
7 |
24 |
--------------------------------------------------------------------------------
/license:
--------------------------------------------------------------------------------
1 | The MIT License
2 |
3 | Copyright (c) Kamran Ahmed
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in
13 | all copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21 | THE SOFTWARE.
--------------------------------------------------------------------------------
/docs/src/layouts/DocsLayout.astro:
--------------------------------------------------------------------------------
1 | ---
2 | import BaseLayout from "./BaseLayout.astro";
3 | import { DocsHeader } from "../components/DocsHeader";
4 | import Container from "../components/Container.astro";
5 | import { getFormattedStars } from "../lib/github";
6 | import Sidebar from "../components/Sidebar.astro";
7 | import type { CollectionEntry } from "astro:content";
8 | import { getAllGuides } from "../lib/guide";
9 |
10 | type GuideType = CollectionEntry<"guides">;
11 |
12 | export interface Props {
13 | guide: GuideType;
14 | }
15 |
16 | const groupedGuides = await getAllGuides();
17 |
18 | const { guide } = Astro.props;
19 | const { groupTitle, sort, title } = guide.data;
20 | ---
21 |
22 |
24 |
26 |
27 |
33 |
30 |
32 |
13 |
--------------------------------------------------------------------------------
/docs/src/content/guides/installation.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Installation"
3 | groupTitle: "Introduction"
4 | sort: 1
5 | ---
6 |
7 | Run one of the following commands to install the package:
8 |
9 | ```bash
10 | # Using npm
11 | npm install driver.js
12 |
13 | # Using pnpm
14 | pnpm install driver.js
15 |
16 | # Using yarn
17 | yarn add driver.js
18 | ```
19 |
20 | Alternatively, you can use CDN and include the script in your HTML file:
21 |
22 | ```html
23 |
24 |
25 | ```
26 |
27 | ## Start Using
28 | Once installed, you can import the package in your project. The following example shows how to highlight an element:
29 |
30 | ```js
31 | import { driver } from "driver.js";
32 | import "driver.js/dist/driver.css";
33 |
34 | const driverObj = driver();
35 | driverObj.highlight({
36 | element: "#some-element",
37 | popover: {
38 | title: "Title",
39 | description: "Description"
40 | }
41 | });
42 | ```
43 |
44 | ### Note on CDN
45 |
46 | If you are using the CDN, you will have to use the package from the `window` object:
47 |
48 | ```js
49 | const driver = window.driver.js.driver;
50 |
51 | const driverObj = driver();
52 |
53 | driverObj.highlight({
54 | element: "#some-element",
55 | popover: {
56 | title: "Title",
57 | description: "Description"
58 | }
59 | });
60 | ```
61 |
62 | Continue reading the [Getting Started](/docs/basic-usage) guide to learn more about the package.
--------------------------------------------------------------------------------
/docs/src/components/OpenSourceLove.astro:
--------------------------------------------------------------------------------
1 | ---
2 | import Container from "./Container.astro";
3 | import { getFormattedStars } from "../lib/github";
4 |
5 | const starCount = getFormattedStars('kamranahmedse/driver.js');
6 | ---
7 |
14 |
41 |
15 |
16 | 
17 |
18 |
19 |
20 | {Object.keys(groupedGuides).map(groupTitle => {
21 | const guides = groupedGuides[groupTitle];
22 |
23 | return (
24 | <>
25 |
17 |
18 | {groupTitle}
26 |-
27 | {guides.map(guide => {
28 | const guidePath = `/docs/${guide.slug}`;
29 | return (
30 |
- 31 | {guide.data.title} 33 | 34 | ); 35 | })} 36 |
8 |
9 |
34 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "driver.js",
3 | "license": "MIT",
4 | "private": false,
5 | "version": "1.3.6",
6 | "main": "./dist/driver.js.cjs",
7 | "module": "./dist/driver.js.mjs",
8 | "types": "./dist/driver.js.d.ts",
9 | "homepage": "https://driverjs.com",
10 | "repository": "https://github.com/kamranahmedse/driver.js",
11 | "author": "Kamran Ahmed
10 | 
32 |
33 |
11 |
31 | Loved by Many
12 |With millions of downloads, Driver.js is an MIT licensed 13 | opensource 14 | project and is used by 15 | thousands of companies around the world.
16 | 17 | 30 |
{ starCount }
32 |
17 |
19 |
20 |
21 |
22 |
25 |
26 |
27 |
30 |
31 |
49 |
50 |
32 | MIT Licensed © 2024
33 |
34 | ·
35 |
36 | Docs
37 |
38 |
39 | GitHub
40 | 
41 |
42 |
43 | Twitter
44 |
45 |
46 |
47 |
16 |
28 |
17 |
18 |
19 | driver.js
20 |
21 |
22 |
19 | driver.js
20 |
21 |
23 |
26 |
27 |
29 | {Object.entries(groupedGuides).map(([category, guides]) => (
30 |
42 |
43 | );
44 | }
45 |
--------------------------------------------------------------------------------
/docs/src/content/guides/styling-overlay.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Styling Overlay"
3 | groupTitle: "Examples"
4 | sort: 5
5 | ---
6 |
7 | import { CodeSample } from "../../components/CodeSample.tsx";
8 |
9 | You can customize the overlay opacity and color using `overlayOpacity` and `overlayColor` options to change the look of the overlay.
10 |
11 | > **Note:** In the examples below we have used `highlight` method to highlight the elements. The same configuration applies to the tour steps as well.
12 |
13 | ## Overlay Color
14 |
15 | Here are some driver.js examples with different overlay colors.
16 |
17 | ```js
18 | import { driver } from "driver.js";
19 | import "driver.js/dist/driver.css";
20 |
21 | const driverObj = driver({
22 | overlayColor: 'red'
23 | });
24 |
25 | driverObj.highlight({
26 | popover: {
27 | title: 'Pass any RGB Color',
28 | description: 'Here we have set the overlay color to be red. You can pass any RGB color to overlayColor option.'
29 | }
30 | });
31 | ```
32 |
33 |
31 |
40 | ))}
41 | {category}
32 |
33 | {guides.map(guide => (
34 |
35 | {guide.data.title}
36 |
37 | ))}
38 |
39 |
34 |
82 |
--------------------------------------------------------------------------------
/docs/src/content/guides/prevent-destroy.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Prevent Tour Exit"
3 | groupTitle: "Examples"
4 | sort: 3
5 | ---
6 |
7 | import { CodeSample } from "../../components/CodeSample.tsx";
8 |
9 | You can also prevent the user from exiting the tour using `allowClose` option. This option is useful when you want to force the user to complete the tour before they can exit.
10 |
11 | In the example below, you won't be able to exit the tour until you reach the last step.
12 |
13 |
6 |
7 |
21 |
22 |
8 |
9 | 
10 | driver.js
11 |
12 |
13 |
14 | Documentation
15 | Docs
16 |
17 | GitHub
18 |
19 |
20 |
10 | driver.js
11 |
12 |
13 |
14 | Documentation
15 | Docs
16 |
17 | GitHub
18 |
19 |
23 |
24 |
52 |
53 |
--------------------------------------------------------------------------------
/docs/src/content/guides/api.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "API Reference"
3 | groupTitle: "Introduction"
4 | sort: 4
5 | ---
6 |
7 | Here is the list of methods provided by `driver` when you initialize it.
8 |
9 | > **Note:** We have omitted the configuration options for brevity. Please look at the configuration section for the options. Links are provided in the description below.
10 |
11 | ```javascript
12 | import { driver } from "driver.js";
13 | import "driver.js/dist/driver.css";
14 |
15 | // Look at the configuration section for the options
16 | // https://driverjs.com/docs/configuration#driver-configuration
17 | const driverObj = driver({ /* ... */ });
18 |
19 | // --------------------------------------------------
20 | // driverObj is an object with the following methods
21 | // --------------------------------------------------
22 |
23 | // Start the tour using `steps` given in the configuration
24 | driverObj.drive(); // Starts at step 0
25 | driverObj.drive(4); // Starts at step 4
26 |
27 | driverObj.moveNext(); // Move to the next step
28 | driverObj.movePrevious(); // Move to the previous step
29 | driverObj.moveTo(4); // Move to the step 4
30 | driverObj.hasNextStep(); // Is there a next step
31 | driverObj.hasPreviousStep() // Is there a previous step
32 |
33 | driverObj.isFirstStep(); // Is the current step the first step
34 | driverObj.isLastStep(); // Is the current step the last step
35 |
36 | driverObj.getActiveIndex(); // Gets the active step index
37 |
38 | driverObj.getActiveStep(); // Gets the active step configuration
39 | driverObj.getPreviousStep(); // Gets the previous step configuration
40 | driverObj.getActiveElement(); // Gets the active HTML element
41 | driverObj.getPreviousElement(); // Gets the previous HTML element
42 |
43 | // Is the tour or highlight currently active
44 | driverObj.isActive();
45 |
46 | // Recalculate and redraw the highlight
47 | driverObj.refresh();
48 |
49 | // Look at the configuration section for configuration options
50 | // https://driverjs.com/docs/configuration#driver-configuration
51 | driverObj.getConfig();
52 | driverObj.setConfig({ /* ... */ });
53 |
54 | driverObj.setSteps([ /* ... */ ]); // Set the steps
55 |
56 | // Look at the state section of configuration for format of the state
57 | // https://driverjs.com/docs/configuration#state
58 | driverObj.getState();
59 |
60 | // Look at the DriveStep section of configuration for format of the step
61 | // https://driverjs.com/docs/configuration/#drive-step-configuration
62 | driverObj.highlight({ /* ... */ }); // Highlight an element
63 |
64 | driverObj.destroy(); // Destroy the tour
65 | ```
--------------------------------------------------------------------------------
/src/utils.ts:
--------------------------------------------------------------------------------
1 | import { getConfig } from "./config";
2 |
3 | export function easeInOutQuad(elapsed: number, initialValue: number, amountOfChange: number, duration: number): number {
4 | if ((elapsed /= duration / 2) < 1) {
5 | return (amountOfChange / 2) * elapsed * elapsed + initialValue;
6 | }
7 | return (-amountOfChange / 2) * (--elapsed * (elapsed - 2) - 1) + initialValue;
8 | }
9 |
10 | export function getFocusableElements(parentEls: Element[] | HTMLElement[]) {
11 | const focusableQuery =
12 | 'a[href]:not([disabled]), button:not([disabled]), textarea:not([disabled]), input[type="text"]:not([disabled]), input[type="radio"]:not([disabled]), input[type="checkbox"]:not([disabled]), select:not([disabled])';
13 |
14 | return parentEls
15 | .flatMap(parentEl => {
16 | const isParentFocusable = parentEl.matches(focusableQuery);
17 | const focusableEls: HTMLElement[] = Array.from(parentEl.querySelectorAll(focusableQuery));
18 |
19 | return [...(isParentFocusable ? [parentEl as HTMLElement] : []), ...focusableEls];
20 | })
21 | .filter(el => {
22 | return getComputedStyle(el).pointerEvents !== "none" && isElementVisible(el);
23 | });
24 | }
25 |
26 | export function bringInView(element: Element) {
27 | if (!element || isElementInView(element)) {
28 | return;
29 | }
30 |
31 | const shouldSmoothScroll = getConfig("smoothScroll");
32 |
33 | const isTallerThanViewport = (element as HTMLElement).offsetHeight > window.innerHeight;
34 |
35 | element.scrollIntoView({
36 | // Removing the smooth scrolling for elements which exist inside the scrollable parent
37 | // This was causing the highlight to not properly render
38 | behavior: !shouldSmoothScroll || hasScrollableParent(element) ? "auto" : "smooth",
39 | inline: "center",
40 | block: isTallerThanViewport ? "start" : "center",
41 | });
42 | }
43 |
44 | function hasScrollableParent(e: Element) {
45 | if (!e || !e.parentElement) {
46 | return;
47 | }
48 |
49 | const parent = e.parentElement as HTMLElement & { scrollTopMax?: number };
50 |
51 | return parent.scrollHeight > parent.clientHeight;
52 | }
53 |
54 | function isElementInView(element: Element) {
55 | const rect = element.getBoundingClientRect();
56 |
57 | return (
58 | rect.top >= 0 &&
59 | rect.left >= 0 &&
60 | rect.bottom <= (window.innerHeight || document.documentElement.clientHeight) &&
61 | rect.right <= (window.innerWidth || document.documentElement.clientWidth)
62 | );
63 | }
64 |
65 | export function isElementVisible(el: HTMLElement) {
66 | return !!(el.offsetWidth || el.offsetHeight || el.getClientRects().length);
67 | }
68 |
--------------------------------------------------------------------------------
/src/config.ts:
--------------------------------------------------------------------------------
1 | import { Driver, DriveStep } from "./driver";
2 | import { AllowedButtons, PopoverDOM } from "./popover";
3 | import { State } from "./state";
4 |
5 | export type DriverHook = (
6 | element: Element | undefined,
7 | step: DriveStep,
8 | opts: { config: Config; state: State; driver: Driver }
9 | ) => void;
10 |
11 | export type Config = {
12 | steps?: DriveStep[];
13 |
14 | animate?: boolean;
15 | overlayColor?: string;
16 | overlayOpacity?: number;
17 | smoothScroll?: boolean;
18 | allowClose?: boolean;
19 | overlayClickBehavior?: "close" | "nextStep";
20 | stagePadding?: number;
21 | stageRadius?: number;
22 |
23 | disableActiveInteraction?: boolean;
24 |
25 | allowKeyboardControl?: boolean;
26 |
27 | // Popover specific configuration
28 | popoverClass?: string;
29 | popoverOffset?: number;
30 | showButtons?: AllowedButtons[];
31 | disableButtons?: AllowedButtons[];
32 | showProgress?: boolean;
33 |
34 | // Button texts
35 | progressText?: string;
36 | nextBtnText?: string;
37 | prevBtnText?: string;
38 | doneBtnText?: string;
39 |
40 | // Called after the popover is rendered
41 | onPopoverRender?: (popover: PopoverDOM, opts: { config: Config; state: State, driver: Driver }) => void;
42 |
43 | // State based callbacks, called upon state changes
44 | onHighlightStarted?: DriverHook;
45 | onHighlighted?: DriverHook;
46 | onDeselected?: DriverHook;
47 | onDestroyStarted?: DriverHook;
48 | onDestroyed?: DriverHook;
49 |
50 | // Event based callbacks, called upon events
51 | onNextClick?: DriverHook;
52 | onPrevClick?: DriverHook;
53 | onCloseClick?: DriverHook;
54 | };
55 |
56 | let currentConfig: Config = {};
57 | let currentDriver: Driver;
58 |
59 | export function configure(config: Config = {}) {
60 | currentConfig = {
61 | animate: true,
62 | allowClose: true,
63 | overlayClickBehavior: "close",
64 | overlayOpacity: 0.7,
65 | smoothScroll: false,
66 | disableActiveInteraction: false,
67 | showProgress: false,
68 | stagePadding: 10,
69 | stageRadius: 5,
70 | popoverOffset: 10,
71 | showButtons: ["next", "previous", "close"],
72 | disableButtons: [],
73 | overlayColor: "#000",
74 | ...config,
75 | };
76 | }
77 |
78 | export function getConfig(): Config;
79 | export function getConfig
25 |
51 |
26 |
47 |
50 | driver.js
27 |28 | Lightweight JavaScript library for product tours, highlights, and contextual help to guide users through your 29 | product. 30 |
31 |
32 |
38 |
43 | Get Started
44 |
45 |
46 | 
49 | 
Driver.js
2 |
3 |
4 |
5 | 
6 |
7 |
8 |
9 |
10 |
11 |
16 | Powerful, highly customizable vanilla JavaScript engine to drive user's focus on the page
17 | No external dependencies, light-weight, supports all major browsers and highly customizable
18 |
21 | 22 | - **Simple**: is simple to use and has no external dependency at all 23 | - **Light-weight**: is just 5kb gzipped as compared to other libraries which are +12kb gzipped 24 | - **Highly customizable**: has a powerful API and can be used however you want 25 | - **Highlight anything**: highlight any (literally any) element on page 26 | - **Feature introductions**: create powerful feature introductions for your web applications 27 | - **Focus shifters**: add focus shifters for users 28 | - **User friendly**: Everything is controllable by keyboard 29 | - **TypeScript**: Written in TypeScript 30 | - **Consistent behavior**: usable across all browsers 31 | - **MIT Licensed**: free for personal and commercial use 32 | 33 |
34 | 35 | ## Documentation 36 | 37 | For demos and documentation, visit [driverjs.com](https://driverjs.com) 38 | 39 |
40 | 41 | ## So, yet another tour library? 42 | 43 | **No**, it's more than a tour library. **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: [highlighting a page component](https://i.imgur.com/TS0LSK9.png) when user is interacting with some component to keep them focused, providing contextual help e.g. popover with dimmed background when user is filling a form, using it as a focus shifter to bring user's attention to some component on page, using it to simulate those "Turn off the Lights" widgets that you might have seen on video players online, usage as a simple modal, and of-course product tours etc. 44 | 45 | Driver.js is written in Vanilla TypeScript, has zero dependencies and is highly customizable. It has several options allowing you to change how it behaves and also **provides you the hooks** to manipulate the elements as they are highlighted, about to be highlighted, or deselected. 46 | 47 | > Also, comparing the size of Driver.js with other libraries, it's the most light-weight, it is **just ~5kb gzipped** while others are 12kb+. 48 | 49 |
50 | 51 | ## Contributions 52 | 53 | Feel free to submit pull requests, create issues or spread the word. 54 | 55 | ## License 56 | 57 | MIT © [Kamran Ahmed](https://twitter.com/kamrify) 58 | -------------------------------------------------------------------------------- /docs/src/content/guides/theming.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Theming" 3 | groupTitle: "Introduction" 4 | sort: 5 5 | --- 6 | 7 | You can customize the look and feel of the driver by adding custom class to popover or applying CSS to different classes used by driver.js. 8 | 9 | ## Styling Popover 10 | 11 | You can set the `popoverClass` option globally in the driver configuration or at the step level to apply custom class to the popover and then use CSS to apply styles. 12 | 13 | ```js 14 | const driverObj = driver({ 15 | popoverClass: 'my-custom-popover-class' 16 | }); 17 | 18 | // or you can also have different classes for different steps 19 | const driverObj2 = driver({ 20 | steps: [ 21 | { 22 | element: '#some-element', 23 | popover: { 24 | title: 'Title', 25 | description: 'Description', 26 | popoverClass: 'my-custom-popover-class' 27 | } 28 | } 29 | ], 30 | }) 31 | ``` 32 | 33 | Here is the list of classes applied to the popover which you can use in conjunction with `popoverClass` option to apply custom styles on the popover. 34 | 35 | ```css 36 | /* Class assigned to popover wrapper */ 37 | .driver-popover {} 38 | 39 | /* Arrow pointing towards the highlighted element */ 40 | .driver-popover-arrow {} 41 | 42 | /* Title and description */ 43 | .driver-popover-title {} 44 | .driver-popover-description {} 45 | 46 | /* Close button displayed on the top right corner */ 47 | .driver-popover-close-btn {} 48 | 49 | /* Footer of the popover displaying progress and navigation buttons */ 50 | .driver-popover-footer {} 51 | .driver-popover-progress-text {} 52 | .driver-popover-prev-btn {} 53 | .driver-popover-next-btn {} 54 | ``` 55 | 56 | Visit the [example page](/docs/styling-popover) for an example that modifies the popover styles. 57 | 58 | ## Modifying Popover DOM 59 | 60 | Alternatively, you can also use the `onPopoverRender` hook to modify the popover DOM before it is displayed. The hook is called with the popover DOM as the first argument. 61 | 62 | ```typescript 63 | type PopoverDOM = { 64 | wrapper: HTMLElement; 65 | arrow: HTMLElement; 66 | title: HTMLElement; 67 | description: HTMLElement; 68 | footer: HTMLElement; 69 | progress: HTMLElement; 70 | previousButton: HTMLElement; 71 | nextButton: HTMLElement; 72 | closeButton: HTMLElement; 73 | footerButtons: HTMLElement; 74 | }; 75 | 76 | onPopoverRender?: (popover: PopoverDOM, opts: { config: Config; state: State }) => void; 77 | ``` 78 | 79 | ## Styling Page 80 | 81 | Following classes are applied to the page when the driver is active. 82 | 83 | ```css 84 | /* Applied to the `body` when the driver: */ 85 | .driver-active {} /* is active */ 86 | .driver-fade {} /* is animated */ 87 | .driver-simple {} /* is not animated */ 88 | ``` 89 | 90 | Following classes are applied to the overlay i.e. the lightbox displayed over the page. 91 | 92 | ```css 93 | .driver-overlay {} 94 | ``` 95 | 96 | ## Styling Highlighted Element 97 | 98 | Whenever an element is highlighted, the following classes are applied to it. 99 | 100 | ```css 101 | .driver-active-element {} 102 | ``` -------------------------------------------------------------------------------- /docs/src/content/guides/basic-usage.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Basic Usage" 3 | groupTitle: "Introduction" 4 | sort: 2 5 | --- 6 | 7 | import { CodeSample } from "../../components/CodeSample.tsx"; 8 | 9 | Once installed, you can import and start using the library. There are several different configuration options available to customize the library. You can find more details about the options in the [configuration section](/docs/configuration). Given below are the basic steps to get started. 10 | 11 | Here is a simple example of how to create a tour with multiple steps. 12 | 13 |
135 | {heading &&
141 | );
142 | }
143 |
--------------------------------------------------------------------------------
/docs/src/content/guides/tour-progress.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Tour Progress"
3 | groupTitle: "Examples"
4 | sort: 2
5 | ---
6 |
7 | import { CodeSample } from "../../components/CodeSample.tsx";
8 |
9 | You can use `showProgress` option to show the progress of the tour. It is shown in the bottom left corner of the screen. There is also `progressText` option which can be used to customize the text shown for the progress.
10 |
11 | Please note that `showProgress` is `false` by default. Also the default text for `progressText` is `{{current}} of {{total}}`. You can use `{{current}}` and `{{total}}` in your `progressText` template to show the current and total steps.
12 |
13 | {heading}
} 136 | {children &&{children}
}
137 |
140 | 
Yet another highlight example.",
72 | }
73 | })
74 | ```
75 |
76 | Focus on the input below and see how the popover is shown.
77 |
78 |
85 |
86 |
7 |
8 |
84 |
85 |
--------------------------------------------------------------------------------
/docs/public/thumbs.svg:
--------------------------------------------------------------------------------
1 |
15 |
--------------------------------------------------------------------------------
/src/driver.css:
--------------------------------------------------------------------------------
1 | .driver-active .driver-overlay {
2 | pointer-events: none;
3 | }
4 |
5 | .driver-active * {
6 | pointer-events: none;
7 | }
8 |
9 | .driver-active .driver-active-element,
10 | .driver-active .driver-active-element *,
11 | .driver-popover,
12 | .driver-popover * {
13 | pointer-events: auto;
14 | }
15 |
16 | @keyframes animate-fade-in {
17 | 0% {
18 | opacity: 0;
19 | }
20 |
21 | to {
22 | opacity: 1;
23 | }
24 | }
25 |
26 | .driver-fade .driver-overlay {
27 | animation: animate-fade-in 200ms ease-in-out;
28 | }
29 |
30 | .driver-fade .driver-popover {
31 | animation: animate-fade-in 200ms;
32 | }
33 |
34 | /* Popover styles */
35 | .driver-popover {
36 | all: unset;
37 | box-sizing: border-box;
38 | color: #2d2d2d;
39 | margin: 0;
40 | padding: 15px;
41 | border-radius: 5px;
42 | min-width: 250px;
43 | max-width: 300px;
44 | box-shadow: 0 1px 10px #0006;
45 | z-index: 1000000000;
46 | position: fixed;
47 | top: 0;
48 | right: 0;
49 | background-color: #fff;
50 | }
51 |
52 | .driver-popover * {
53 | font-family: "Helvetica Neue", Inter, ui-sans-serif, "Apple Color Emoji", Helvetica, Arial, sans-serif;
54 | }
55 |
56 | .driver-popover-title {
57 | font: 19px / normal sans-serif;
58 | font-weight: 700;
59 | display: block;
60 | position: relative;
61 | line-height: 1.5;
62 | zoom: 1;
63 | margin: 0;
64 | }
65 |
66 | .driver-popover-close-btn {
67 | all: unset;
68 | position: absolute;
69 | top: 0;
70 | right: 0;
71 | width: 32px;
72 | height: 28px;
73 | cursor: pointer;
74 | font-size: 18px;
75 | font-weight: 500;
76 | color: #d2d2d2;
77 | z-index: 1;
78 | text-align: center;
79 | transition: color;
80 | transition-duration: 200ms;
81 | }
82 |
83 | .driver-popover-close-btn:hover,
84 | .driver-popover-close-btn:focus {
85 | color: #2d2d2d;
86 | }
87 |
88 | .driver-popover-title[style*="block"] + .driver-popover-description {
89 | margin-top: 5px;
90 | }
91 |
92 | .driver-popover-description {
93 | margin-bottom: 0;
94 | font: 14px / normal sans-serif;
95 | line-height: 1.5;
96 | font-weight: 400;
97 | zoom: 1;
98 | }
99 |
100 | .driver-popover-footer {
101 | margin-top: 15px;
102 | text-align: right;
103 | zoom: 1;
104 | display: flex;
105 | align-items: center;
106 | justify-content: space-between;
107 | }
108 |
109 | .driver-popover-progress-text {
110 | font-size: 13px;
111 | font-weight: 400;
112 | color: #727272;
113 | zoom: 1;
114 | }
115 |
116 | .driver-popover-footer button {
117 | all: unset;
118 | display: inline-block;
119 | box-sizing: border-box;
120 | padding: 3px 7px;
121 | text-decoration: none;
122 | text-shadow: 1px 1px 0 #fff;
123 | background-color: #ffffff;
124 | color: #2d2d2d;
125 | font: 12px / normal sans-serif;
126 | cursor: pointer;
127 | outline: 0;
128 | zoom: 1;
129 | line-height: 1.3;
130 | border: 1px solid #ccc;
131 | border-radius: 3px;
132 | }
133 |
134 | .driver-popover-footer .driver-popover-btn-disabled {
135 | opacity: 0.5;
136 | pointer-events: none;
137 | }
138 |
139 | /* Disable the scrolling of parent element if it has an active element*/
140 | :not(body):has(> .driver-active-element) {
141 | overflow: hidden !important;
142 | }
143 |
144 | .driver-no-interaction, .driver-no-interaction * {
145 | pointer-events: none !important;
146 | }
147 |
148 | .driver-popover-footer button:hover,
149 | .driver-popover-footer button:focus {
150 | background-color: #f7f7f7;
151 | }
152 |
153 | .driver-popover-navigation-btns {
154 | display: flex;
155 | flex-grow: 1;
156 | justify-content: flex-end;
157 | }
158 |
159 | .driver-popover-navigation-btns button + button {
160 | margin-left: 4px;
161 | }
162 |
163 | .driver-popover-arrow {
164 | content: "";
165 | position: absolute;
166 | border: 5px solid #fff;
167 | }
168 |
169 | .driver-popover-arrow-side-over {
170 | display: none;
171 | }
172 |
173 | /** Popover Arrow Sides **/
174 | .driver-popover-arrow-side-left {
175 | left: 100%;
176 | border-right-color: transparent;
177 | border-bottom-color: transparent;
178 | border-top-color: transparent;
179 | }
180 |
181 | .driver-popover-arrow-side-right {
182 | right: 100%;
183 | border-left-color: transparent;
184 | border-bottom-color: transparent;
185 | border-top-color: transparent;
186 | }
187 |
188 | .driver-popover-arrow-side-top {
189 | top: 100%;
190 | border-right-color: transparent;
191 | border-bottom-color: transparent;
192 | border-left-color: transparent;
193 | }
194 |
195 | .driver-popover-arrow-side-bottom {
196 | bottom: 100%;
197 | border-left-color: transparent;
198 | border-top-color: transparent;
199 | border-right-color: transparent;
200 | }
201 |
202 | .driver-popover-arrow-side-center {
203 | display: none;
204 | }
205 |
206 | /* Left/Start + Right/Start */
207 | .driver-popover-arrow-side-left.driver-popover-arrow-align-start,
208 | .driver-popover-arrow-side-right.driver-popover-arrow-align-start {
209 | top: 15px;
210 | }
211 |
212 | /* Top/Start + Bottom/Start */
213 | .driver-popover-arrow-side-top.driver-popover-arrow-align-start,
214 | .driver-popover-arrow-side-bottom.driver-popover-arrow-align-start {
215 | left: 15px;
216 | }
217 |
218 | /* End/Left + End/Right */
219 | .driver-popover-arrow-align-end.driver-popover-arrow-side-left,
220 | .driver-popover-arrow-align-end.driver-popover-arrow-side-right {
221 | bottom: 15px;
222 | }
223 |
224 | /* Top/End + Bottom/End */
225 | .driver-popover-arrow-side-top.driver-popover-arrow-align-end,
226 | .driver-popover-arrow-side-bottom.driver-popover-arrow-align-end {
227 | right: 15px;
228 | }
229 |
230 | /* Left/Center + Right/Center */
231 | .driver-popover-arrow-side-left.driver-popover-arrow-align-center,
232 | .driver-popover-arrow-side-right.driver-popover-arrow-align-center {
233 | top: 50%;
234 | margin-top: -5px;
235 | }
236 |
237 | /* Top/Center + Bottom/Center */
238 | .driver-popover-arrow-side-top.driver-popover-arrow-align-center,
239 | .driver-popover-arrow-side-bottom.driver-popover-arrow-align-center {
240 | left: 50%;
241 | margin-left: -5px;
242 | }
243 |
244 | /* No arrow */
245 | .driver-popover-arrow-none {
246 | display: none;
247 | }
248 |
--------------------------------------------------------------------------------
/docs/public/favicon.svg:
--------------------------------------------------------------------------------
1 |
18 |
--------------------------------------------------------------------------------
/docs/public/driver-head.svg:
--------------------------------------------------------------------------------
1 |
18 |
--------------------------------------------------------------------------------
/src/overlay.ts:
--------------------------------------------------------------------------------
1 | import { easeInOutQuad } from "./utils";
2 | import { onDriverClick } from "./events";
3 | import { emit } from "./emitter";
4 | import { getConfig } from "./config";
5 | import { getState, setState } from "./state";
6 |
7 | export type StageDefinition = {
8 | x: number;
9 | y: number;
10 | width: number;
11 | height: number;
12 | };
13 |
14 | // This method calculates the animated new position of the
15 | // stage (called for each frame by requestAnimationFrame)
16 | export function transitionStage(elapsed: number, duration: number, from: Element, to: Element) {
17 | let activeStagePosition = getState("__activeStagePosition");
18 |
19 | const fromDefinition = activeStagePosition ? activeStagePosition : from.getBoundingClientRect();
20 | const toDefinition = to.getBoundingClientRect();
21 |
22 | const x = easeInOutQuad(elapsed, fromDefinition.x, toDefinition.x - fromDefinition.x, duration);
23 | const y = easeInOutQuad(elapsed, fromDefinition.y, toDefinition.y - fromDefinition.y, duration);
24 | const width = easeInOutQuad(elapsed, fromDefinition.width, toDefinition.width - fromDefinition.width, duration);
25 | const height = easeInOutQuad(elapsed, fromDefinition.height, toDefinition.height - fromDefinition.height, duration);
26 |
27 | activeStagePosition = {
28 | x,
29 | y,
30 | width,
31 | height,
32 | };
33 |
34 | renderOverlay(activeStagePosition);
35 | setState("__activeStagePosition", activeStagePosition);
36 | }
37 |
38 | export function trackActiveElement(element: Element) {
39 | if (!element) {
40 | return;
41 | }
42 |
43 | const definition = element.getBoundingClientRect();
44 |
45 | const activeStagePosition: StageDefinition = {
46 | x: definition.x,
47 | y: definition.y,
48 | width: definition.width,
49 | height: definition.height,
50 | };
51 |
52 | setState("__activeStagePosition", activeStagePosition);
53 |
54 | renderOverlay(activeStagePosition);
55 | }
56 |
57 | export function refreshOverlay() {
58 | const activeStagePosition = getState("__activeStagePosition");
59 | const overlaySvg = getState("__overlaySvg");
60 |
61 | if (!activeStagePosition) {
62 | return;
63 | }
64 |
65 | if (!overlaySvg) {
66 | console.warn("No stage svg found.");
67 | return;
68 | }
69 |
70 | const windowX = window.innerWidth;
71 | const windowY = window.innerHeight;
72 |
73 | overlaySvg.setAttribute("viewBox", `0 0 ${windowX} ${windowY}`);
74 | }
75 |
76 | function mountOverlay(stagePosition: StageDefinition) {
77 | const overlaySvg = createOverlaySvg(stagePosition);
78 | document.body.appendChild(overlaySvg);
79 |
80 | onDriverClick(overlaySvg, e => {
81 | const target = e.target as SVGElement;
82 | if (target.tagName !== "path") {
83 | return;
84 | }
85 |
86 | emit("overlayClick");
87 | });
88 |
89 | setState("__overlaySvg", overlaySvg);
90 | }
91 |
92 | function renderOverlay(stagePosition: StageDefinition) {
93 | const overlaySvg = getState("__overlaySvg");
94 |
95 | // TODO: cancel rendering if element is not visible
96 | if (!overlaySvg) {
97 | mountOverlay(stagePosition);
98 |
99 | return;
100 | }
101 |
102 | const pathElement = overlaySvg.firstElementChild as SVGPathElement | null;
103 | if (pathElement?.tagName !== "path") {
104 | throw new Error("no path element found in stage svg");
105 | }
106 |
107 | pathElement.setAttribute("d", generateStageSvgPathString(stagePosition));
108 | }
109 |
110 | function createOverlaySvg(stage: StageDefinition): SVGSVGElement {
111 | const windowX = window.innerWidth;
112 | const windowY = window.innerHeight;
113 |
114 | const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
115 | svg.classList.add("driver-overlay", "driver-overlay-animated");
116 |
117 | svg.setAttribute("viewBox", `0 0 ${windowX} ${windowY}`);
118 | svg.setAttribute("xmlSpace", "preserve");
119 | svg.setAttribute("xmlnsXlink", "http://www.w3.org/1999/xlink");
120 | svg.setAttribute("version", "1.1");
121 | svg.setAttribute("preserveAspectRatio", "xMinYMin slice");
122 |
123 | svg.style.fillRule = "evenodd";
124 | svg.style.clipRule = "evenodd";
125 | svg.style.strokeLinejoin = "round";
126 | svg.style.strokeMiterlimit = "2";
127 | svg.style.zIndex = "10000";
128 | svg.style.position = "fixed";
129 | svg.style.top = "0";
130 | svg.style.left = "0";
131 | svg.style.width = "100%";
132 | svg.style.height = "100%";
133 |
134 | const stagePath = document.createElementNS("http://www.w3.org/2000/svg", "path");
135 |
136 | stagePath.setAttribute("d", generateStageSvgPathString(stage));
137 |
138 | stagePath.style.fill = getConfig("overlayColor") || "rgb(0,0,0)";
139 | stagePath.style.opacity = `${getConfig("overlayOpacity")}`;
140 | stagePath.style.pointerEvents = "auto";
141 | stagePath.style.cursor = "auto";
142 |
143 | svg.appendChild(stagePath);
144 |
145 | return svg;
146 | }
147 |
148 | function generateStageSvgPathString(stage: StageDefinition) {
149 | const windowX = window.innerWidth;
150 | const windowY = window.innerHeight;
151 |
152 | const stagePadding = getConfig("stagePadding") || 0;
153 | const stageRadius = getConfig("stageRadius") || 0;
154 |
155 | const stageWidth = stage.width + stagePadding * 2;
156 | const stageHeight = stage.height + stagePadding * 2;
157 |
158 | // prevent glitches when stage is too small for radius
159 | const limitedRadius = Math.min(stageRadius, stageWidth / 2, stageHeight / 2);
160 |
161 | // no value below 0 allowed + round down
162 | const normalizedRadius = Math.floor(Math.max(limitedRadius, 0));
163 |
164 | const highlightBoxX = stage.x - stagePadding + normalizedRadius;
165 | const highlightBoxY = stage.y - stagePadding;
166 | const highlightBoxWidth = stageWidth - normalizedRadius * 2;
167 | const highlightBoxHeight = stageHeight - normalizedRadius * 2;
168 |
169 | return `M${windowX},0L0,0L0,${windowY}L${windowX},${windowY}L${windowX},0Z
170 | M${highlightBoxX},${highlightBoxY} h${highlightBoxWidth} a${normalizedRadius},${normalizedRadius} 0 0 1 ${normalizedRadius},${normalizedRadius} v${highlightBoxHeight} a${normalizedRadius},${normalizedRadius} 0 0 1 -${normalizedRadius},${normalizedRadius} h-${highlightBoxWidth} a${normalizedRadius},${normalizedRadius} 0 0 1 -${normalizedRadius},-${normalizedRadius} v-${highlightBoxHeight} a${normalizedRadius},${normalizedRadius} 0 0 1 ${normalizedRadius},-${normalizedRadius} z`;
171 | }
172 |
173 | export function destroyOverlay() {
174 | const overlaySvg = getState("__overlaySvg");
175 | if (overlaySvg) {
176 | overlaySvg.remove();
177 | }
178 | }
179 |
--------------------------------------------------------------------------------
/docs/src/content/guides/migrating-from-0x.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Migrate to 1.x"
3 | groupTitle: "Introduction"
4 | sort: 6
5 | ---
6 |
7 | Drivers 1.x is a major release that introduces a new API and a new architecture. This page will help you migrate your code from 0.x to 1.x.
8 |
9 | > Change in how you import the library
10 | ```diff
11 | - import Driver from 'driver.js';
12 | - import 'driver.js/dist/driver.min.css';
13 | + import { driver } from 'driver.js';
14 | + import "driver.js/dist/driver.css";
15 | ```
16 |
17 | > Change in how you initialize the library
18 | ```diff
19 | - const driverObj = new Driver(config);
20 | - driverObj.setSteps(steps);
21 |
22 | + // Steps can be passed in the constructor
23 | + const driverObj = driver({
24 | + ...config,
25 | + steps
26 | + });
27 | ```
28 |
29 | > Changes in configuration
30 |
31 | ```diff
32 | const config = {
33 | - overlayClickNext: false, // Option has been removed
34 | - closeBtnText: 'Close', // Option has been removed (close button is now an icon)
35 | - scrollIntoViewOptions: {}, // Option has been renamed
36 | - opacity: 0.75,
37 | + overlayOpacity: 0.75,
38 | - className: 'scoped-class',
39 | + popoverClass: 'scoped-class',
40 | - padding: 10,
41 | + stagePadding: 10,
42 | - showButtons: false,
43 | + showButtons: ['next', 'prev', 'close'], // pass an array of buttons to show
44 | - keyboardControl: true,
45 | + allowKeyboardControl: true,
46 | - onHighlightStarted: (Element) {},
47 | + onHighlightStarted?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
48 | - onHighlighted: (Element) {},
49 | + onHighlighted?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
50 | - onDeselected: (Element) {}, // Called when element has been deselected
51 | + onDeselected?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
52 |
53 | - onReset: (Element) {}, // Called when overlay is about to be cleared
54 | + onDestroyStarted?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
55 | + onDestroyed?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
56 | + onCloseClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
57 |
58 | - onNext: (Element) => {}, // Called when moving to next step on any step
59 | - onPrevious: (Element) => {}, // Called when moving to next step on any step
60 | + // By overriding the default onNextClick and onPrevClick, you control the flow of the driver
61 | + // Visit for more details: https://driverjs.com/docs/configuration
62 | + onNextClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
63 | + onPrevClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
64 |
65 | + // New options added
66 | + overlayColor?: string;
67 | + stageRadius?: number;
68 | + popoverOffset?: number;
69 | + disableButtons?: ["next", "prev", "close"];
70 | + showProgress?: boolean;
71 | + progressText?: string;
72 | + onPopoverRender?: (popover: PopoverDOM, options: { config: Config; state: State }) => void;
73 | }
74 | ```
75 |
76 | > Changes in step and popover definition
77 |
78 | ```diff
79 | const stepDefinition = {
80 | popover: {
81 | - closeBtnText: 'Close', // Removed, close button is an icon
82 | - element: '.some-element', // Required
83 | + element: '.some-element', // Optional, if not provided, step will be shown as modal
84 | - className: 'popover-class',
85 | + popoverClass: string;
86 | - showButtons: false,
87 | + showButtons: ["next", "previous", "close"]; // Array of buttons to show
88 | - title: ''; // Required
89 | + title: ''; // Optional
90 | - description: ''; // Required
91 | + description: ''; // Optional
92 |
93 | - // position can be left, left-center, left-bottom, top,
94 | - // top-center, top-right, right, right-center, right-bottom,
95 | - // bottom, bottom-center, bottom-right, mid-center
96 | - position: 'left',
97 | + // Now you need to specify the side and align separately
98 | + side?: "top" | "right" | "bottom" | "left";
99 | + align?: "start" | "center" | "end";
100 |
101 | + // New options
102 | + showProgress?: boolean;
103 | + progressText?: string;
104 | + onPopoverRender?: (popover: PopoverDOM, options: { config: Config; state: State }) => void;
105 | + onNextClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
106 | + onPrevClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
107 | + onCloseClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
108 | }
109 |
110 | + // New hook to control the flow of the driver
111 | + onDeselected?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
112 | + onHighlightStarted?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
113 | + onHighlighted?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
114 | };
115 | ```
116 |
117 | > Changes in API methods.
118 |
119 | ```diff
120 | - driverObj.preventMove(); // async support is built-in, no longer need to call this
121 | - activeElement.getCalculatedPosition();
122 | - activeElement.hidePopover();
123 | - activeElement.showPopover();
124 | - activeElement.getNode();
125 |
126 | - const isActivated = driverObj.isActivated;
127 | + const isActivated = driverObj.isActive();
128 |
129 | - driverObj.start(stepNumber = 0);
130 | + driverObj.drive(stepNumber = 0);
131 |
132 | - driverObj.highlight(string|stepDefinition);
133 | + driverObj.highlight(stepDefinition)
134 |
135 | - driverObj.reset();
136 | + driverObj.destroy();
137 |
138 | - driverObj.hasHighlightedElement();
139 | + typeof driverObj.getActiveElement() !== 'undefined';
140 |
141 | - driverObj.getHighlightedElement();
142 | + driverObj.getActiveElement();
143 |
144 | - driverObj.getLastHighlightedElement();
145 | + driverObj.getPreviousElement();
146 |
147 | + // New options added
148 | + driverObj.moveTo(stepIndex)
149 | + driverObj.getActiveStep(); // returns the configured step definition
150 | + driverObj.getPreviousStep(); // returns the previous step definition
151 | + driverObj.isLastStep();
152 | + driverObj.isFirstStep();
153 | + driverObj.getState();
154 | + driverObj.getConfig();
155 | + driverObj.setConfig(config);
156 | + driverObj.refresh();
157 | ```
158 |
159 | Please make sure to visit the [documentation](https://driverjs.com/docs/configuration) for more details.
--------------------------------------------------------------------------------
/src/highlight.ts:
--------------------------------------------------------------------------------
1 | import { DriveStep } from "./driver";
2 | import { refreshOverlay, trackActiveElement, transitionStage } from "./overlay";
3 | import { getConfig, getCurrentDriver } from "./config";
4 | import { hidePopover, renderPopover, repositionPopover } from "./popover";
5 | import { bringInView } from "./utils";
6 | import { getState, setState } from "./state";
7 |
8 | function mountDummyElement(): Element {
9 | const existingDummy = document.getElementById("driver-dummy-element");
10 | if (existingDummy) {
11 | return existingDummy;
12 | }
13 |
14 | let element = document.createElement("div");
15 |
16 | element.id = "driver-dummy-element";
17 | element.style.width = "0";
18 | element.style.height = "0";
19 | element.style.pointerEvents = "none";
20 | element.style.opacity = "0";
21 | element.style.position = "fixed";
22 | element.style.top = "50%";
23 | element.style.left = "50%";
24 |
25 | document.body.appendChild(element);
26 |
27 | return element;
28 | }
29 |
30 | export function highlight(step: DriveStep) {
31 | const { element } = step;
32 | let elemObj =
33 | typeof element === "function" ? element() : typeof element === "string" ? document.querySelector(element) : element;
34 |
35 | // If the element is not found, we mount a 1px div
36 | // at the center of the screen to highlight and show
37 | // the popover on top of that. This is to show a
38 | // modal-like highlight.
39 | if (!elemObj) {
40 | elemObj = mountDummyElement();
41 | }
42 |
43 | transferHighlight(elemObj, step);
44 | }
45 |
46 | export function refreshActiveHighlight() {
47 | const activeHighlight = getState("__activeElement");
48 | const activeStep = getState("__activeStep")!;
49 |
50 | if (!activeHighlight) {
51 | return;
52 | }
53 |
54 | trackActiveElement(activeHighlight);
55 | refreshOverlay();
56 | repositionPopover(activeHighlight, activeStep);
57 | }
58 |
59 | function transferHighlight(toElement: Element, toStep: DriveStep) {
60 | const duration = 400;
61 | const start = Date.now();
62 |
63 | const fromStep = getState("__activeStep");
64 | const fromElement = getState("__activeElement") || toElement;
65 |
66 | // If it's the first time we're highlighting an element, we show
67 | // the popover immediately. Otherwise, we wait for the animation
68 | // to finish before showing the popover.
69 | const isFirstHighlight = !fromElement || fromElement === toElement;
70 | const isToDummyElement = toElement.id === "driver-dummy-element";
71 | const isFromDummyElement = fromElement.id === "driver-dummy-element";
72 |
73 | const isAnimatedTour = getConfig("animate");
74 | const highlightStartedHook = toStep.onHighlightStarted || getConfig("onHighlightStarted");
75 | const highlightedHook = toStep?.onHighlighted || getConfig("onHighlighted");
76 | const deselectedHook = fromStep?.onDeselected || getConfig("onDeselected");
77 |
78 | const config = getConfig();
79 | const state = getState();
80 |
81 | if (!isFirstHighlight && deselectedHook) {
82 | deselectedHook(isFromDummyElement ? undefined : fromElement, fromStep!, {
83 | config,
84 | state,
85 | driver: getCurrentDriver(),
86 | });
87 | }
88 |
89 | if (highlightStartedHook) {
90 | highlightStartedHook(isToDummyElement ? undefined : toElement, toStep, {
91 | config,
92 | state,
93 | driver: getCurrentDriver(),
94 | });
95 | }
96 |
97 | const hasDelayedPopover = !isFirstHighlight && isAnimatedTour;
98 | let isPopoverRendered = false;
99 |
100 | hidePopover();
101 |
102 | setState("previousStep", fromStep);
103 | setState("previousElement", fromElement);
104 | setState("activeStep", toStep);
105 | setState("activeElement", toElement);
106 |
107 | const animate = () => {
108 | const transitionCallback = getState("__transitionCallback");
109 |
110 | // This makes sure that the repeated calls to transferHighlight
111 | // don't interfere with each other. Only the last call will be
112 | // executed.
113 | if (transitionCallback !== animate) {
114 | return;
115 | }
116 |
117 | const elapsed = Date.now() - start;
118 | const timeRemaining = duration - elapsed;
119 | const isHalfwayThrough = timeRemaining <= duration / 2;
120 |
121 | if (toStep.popover && isHalfwayThrough && !isPopoverRendered && hasDelayedPopover) {
122 | renderPopover(toElement, toStep);
123 | isPopoverRendered = true;
124 | }
125 |
126 | if (getConfig("animate") && elapsed < duration) {
127 | transitionStage(elapsed, duration, fromElement, toElement);
128 | } else {
129 | trackActiveElement(toElement);
130 |
131 | if (highlightedHook) {
132 | highlightedHook(isToDummyElement ? undefined : toElement, toStep, {
133 | config: getConfig(),
134 | state: getState(),
135 | driver: getCurrentDriver(),
136 | });
137 | }
138 |
139 | setState("__transitionCallback", undefined);
140 | setState("__previousStep", fromStep);
141 | setState("__previousElement", fromElement);
142 | setState("__activeStep", toStep);
143 | setState("__activeElement", toElement);
144 | }
145 |
146 | window.requestAnimationFrame(animate);
147 | };
148 |
149 | setState("__transitionCallback", animate);
150 |
151 | window.requestAnimationFrame(animate);
152 |
153 | bringInView(toElement);
154 | if (!hasDelayedPopover && toStep.popover) {
155 | renderPopover(toElement, toStep);
156 | }
157 |
158 | fromElement.classList.remove("driver-active-element", "driver-no-interaction");
159 | fromElement.removeAttribute("aria-haspopup");
160 | fromElement.removeAttribute("aria-expanded");
161 | fromElement.removeAttribute("aria-controls");
162 |
163 | const disableActiveInteraction = toStep.disableActiveInteraction ?? getConfig("disableActiveInteraction");
164 | if (disableActiveInteraction) {
165 | toElement.classList.add("driver-no-interaction");
166 | }
167 |
168 | toElement.classList.add("driver-active-element");
169 | toElement.setAttribute("aria-haspopup", "dialog");
170 | toElement.setAttribute("aria-expanded", "true");
171 | toElement.setAttribute("aria-controls", "driver-popover-content");
172 | }
173 |
174 | export function destroyHighlight() {
175 | document.getElementById("driver-dummy-element")?.remove();
176 | document.querySelectorAll(".driver-active-element").forEach(element => {
177 | element.classList.remove("driver-active-element", "driver-no-interaction");
178 | element.removeAttribute("aria-haspopup");
179 | element.removeAttribute("aria-expanded");
180 | element.removeAttribute("aria-controls");
181 | });
182 | }
183 |
--------------------------------------------------------------------------------
/docs/src/content/guides/styling-popover.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Styling Popover"
3 | groupTitle: "Examples"
4 | sort: 2
5 | ---
6 |
7 | import { CodeSample } from "../../components/CodeSample.tsx";
8 |
9 | You can either use the default class names and override the styles or you can pass a custom class name to the `popoverClass` option either globally or per step.
10 |
11 | Alternatively, if want to modify the Popover DOM, you can use the `onPopoverRender` callback to get the popover DOM element and do whatever you want with it before popover is rendered.
12 |
13 | We have added a few examples below but have a look at the [theming section](/docs/theming#styling-popover) for detailed guide including class names to target etc.
14 |
15 |
9 |
14 | Nothing else like it
10 |11 | Lightweight with no external dependencies, supports all major browsers and is highly customizable. 12 |
13 |
15 |
83 |
16 |
24 |
17 |
19 | Browser Support
20 |21 | Works in all modern browsers including Chrome, IE9+, Safari, Firefox and Opera 22 |
23 |
25 |
31 |
26 |
28 | Mobile Ready
29 |Works on desktop, tablets and mobile devices
30 |
32 |
38 |
33 |
35 | Highly Customizable
36 |Powerful API that allows you to customize it to your needs
37 |
39 |
47 |
40 |
42 | Lightweight
43 |44 | Only 5KB minified, compared to other libraries which are typically >12KB minified 45 |
46 |
48 |
54 |
49 |
51 | No Dependencies
52 |Simple to use with absolutely no external dependencies
53 |
55 |
61 |
56 |
58 | Feature Rich
59 |Create powerful feature introductions for your web applications
60 |
62 |
68 |
63 | MIT
64 |
65 | MIT License
66 |Free for both personal and commercial use
67 |
69 |
75 |
70 |
72 | Keyboard Control
73 |All actions can be controlled via keyboard
74 |
76 |
82 |
77 | ALL
78 |
79 | Highlight Anything
80 |Highlight any element on the page
81 |141 | 142 |
30 |
32 |
33 | Use the buttons below to show the popover.
31 |
34 | left and align set to start. PS, we can use HTML in the title and descriptions of popover.',
41 | side: "left",
42 | align: 'start'
43 | }
44 | }}
45 | id={"left-start"}
46 | client:load
47 | />
48 |
49 | left and align set to center. PS, we can use HTML in the title and descriptions of popover.',
56 | side: "left",
57 | align: 'center'
58 | }
59 | }}
60 | id={"left-start"}
61 | client:load
62 | />
63 |
64 | left and align set to end. PS, we can use HTML in the title and descriptions of popover.',
71 | side: "left",
72 | align: 'end'
73 | }
74 | }}
75 | id={"left-start"}
76 | client:load
77 | />
78 |
79 | top and align set to start. PS, we can use HTML in the title and descriptions of popover.',
86 | side: "top",
87 | align: 'start'
88 | }
89 | }}
90 | id={"top-start"}
91 | client:load
92 | />
93 |
94 | top and align set to center. PS, we can use HTML in the title and descriptions of popover.',
101 | side: "top",
102 | align: 'center'
103 | }
104 | }}
105 | id={"top-start"}
106 | client:load
107 | />
108 |
109 | top and align set to end. PS, we can use HTML in the title and descriptions of popover.',
116 | side: "top",
117 | align: 'end'
118 | }
119 | }}
120 | id={"top-start"}
121 | client:load
122 | />
123 |
124 | right and align set to start. PS, we can use HTML in the title and descriptions of popover.',
131 | side: "right",
132 | align: 'start'
133 | }
134 | }}
135 | id={"right-start"}
136 | client:load
137 | />
138 |
139 | right and align set to center. PS, we can use HTML in the title and descriptions of popover.',
146 | side: "right",
147 | align: 'center'
148 | }
149 | }}
150 | id={"right-start"}
151 | client:load
152 | />
153 |
154 | right and align set to end. PS, we can use HTML in the title and descriptions of popover.',
161 | side: "right",
162 | align: 'end'
163 | }
164 | }}
165 | id={"right-start"}
166 | client:load
167 | />
168 |
169 | bottom and align set to start. PS, we can use HTML in the title and descriptions of popover.',
176 | side: "bottom",
177 | align: 'start'
178 | }
179 | }}
180 | id={"bottom-start"}
181 | client:load
182 | />
183 |
184 | bottom and align set to center. PS, we can use HTML in the title and descriptions of popover.',
191 | side: "bottom",
192 | align: 'center'
193 | }
194 | }}
195 | id={"bottom-start"}
196 | client:load
197 | />
198 |
199 | bottom and align set to end. PS, we can use HTML in the title and descriptions of popover.',
206 | side: "bottom",
207 | align: 'end'
208 | }
209 | }}
210 | id={"right-start"}
211 | client:load
212 | />
213 |
--------------------------------------------------------------------------------
/docs/src/content/guides/buttons.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Popover Buttons"
3 | groupTitle: "Examples"
4 | sort: 9
5 | ---
6 |
7 | import { CodeSample } from "../../components/CodeSample.tsx";
8 |
9 | You can use the `showButtons` option to choose which buttons to show in the popover. The default value is `['next', 'previous', 'close']`.
10 |
11 |
12 | > **Note:** When using the `highlight` method to highlight a single element, the only button shown is the `close`
13 | button. However, you can use the `showButtons` option to show other buttons as well. But the buttons won't do
14 | anything. You will have to use the `onNextClick` and `onPreviousClick` callbacks to implement the functionality.
15 |
16 |
17 |
18 |
45 | ```js
46 | import { driver } from "driver.js";
47 | import "driver.js/dist/driver.css";
48 |
49 | const driverObj = driver({
50 | showButtons: [
51 | 'next',
52 | 'previous',
53 | 'close'
54 | ],
55 | steps: [
56 | {
57 | element: '#first-element',
58 | popover: {
59 | title: 'Popover Title',
60 | description: 'Popover Description'
61 | }
62 | },
63 | {
64 | element: '#second-element',
65 | popover: {
66 | title: 'Popover Title',
67 | description: 'Popover Description'
68 | }
69 | }
70 | ]
71 | });
72 |
73 | driverObj.drive();
74 | ```
75 |
76 |
128 |
129 | ## Change Button Text
130 |
131 | You can also change the text of buttons using `nextBtnText`, `prevBtnText` and `doneBtnText` options.
132 |
133 |
134 | ',
140 | prevBtnText: '<--',
141 | doneBtnText: 'X',
142 | }}
143 | tour={[
144 | {
145 | element: '#code-sample-3',
146 | popover: {
147 | title: 'Popover Title',
148 | description: 'Popover Description'
149 | }
150 | },
151 | {
152 | element: '#code-sample-3 code',
153 | popover: {
154 | title: 'Popover Title',
155 | description: 'Popover Description'
156 | }
157 | }
158 | ]}
159 | id={"code-sample-3"}
160 | client:load>
161 | ```js
162 | import { driver } from "driver.js";
163 | import "driver.js/dist/driver.css";
164 |
165 | const driverObj = driver({
166 | nextBtnText: '—›',
167 | prevBtnText: '‹—',
168 | doneBtnText: '✕',
169 | showProgress: true,
170 | steps: [
171 | // ...
172 | ]
173 | });
174 |
175 | driverObj.drive();
176 | ```
177 |
178 |
179 |
180 | ## Event Handlers
181 |
182 | You can use the `onNextClick`, `onPreviousClick` and `onCloseClick` callbacks to implement custom functionality when the user clicks on the next and previous buttons.
183 |
184 | > Please note that when you configure these callbacks, the default functionality of the buttons will be disabled. You will have to implement the functionality yourself.
185 |
186 | Examples
5 |Here are just a few examples; find more in the documentation.
7 | 8 |
9 |
27 |
28 |
--------------------------------------------------------------------------------