opensource/driver.js
3
0
Fork 0
mirror of https://github.com/kamranahmedse/driver.js.git synced 2026-10-30 19:27:40 +08:00
Code Issues Packages Projects Releases Wiki Activity

Document hints on the Configuration and API Reference pages

Browse Source 
Hints were only covered by their own guide. Configuration gains the
HintsConfig and DriverHint sections in the same annotated-type style as
the tour's, and API Reference gains the hints() factory with every
instance method. Both cross-link the guide, and the API page links the
new configuration anchor. Also replaces a pre-existing em dash in the
onDoneClick note.
This commit is contained in:
Kamran Ahmed
2026-07-17 09:55:59 +01:00
parent 09484c7261
commit cd50754091
2 changed files with 223 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/src/content/guides/api.mdx
+62 -8
View File
@@ -1,6 +1,6 @@
---
title: "API Reference"
description: "Complete Driver.js API reference: drive, moveNext, highlight, destroy, getActiveStep and every method available on the driver instance, with examples."
description: "Complete Driver.js API reference: every method available on the driver and hints instances, with examples."
groupTitle: "Introduction"
sort: 4
---
@@ -15,21 +15,23 @@ import "driver.js/dist/driver.css";
// Look at the configuration section for the options
// https://driverjs.com/docs/configuration#driver-configuration
const driverObj = driver({ /* ... */ });
const driverObj = driver({
/* ... */
});
// --------------------------------------------------
// driverObj is an object with the following methods
// --------------------------------------------------
// Start the tour using `steps` given in the configuration
driverObj.drive(); // Starts at step 0
driverObj.drive(); // Starts at step 0
driverObj.drive(4); // Starts at step 4
driverObj.moveNext(); // Move to the next step
driverObj.movePrevious(); // Move to the previous step
driverObj.moveTo(4); // Move to the step 4
driverObj.hasNextStep(); // Is there a next step
driverObj.hasPreviousStep() // Is there a previous step
driverObj.hasPreviousStep(); // Is there a previous step
driverObj.isFirstStep(); // Is the current step the first step
driverObj.isLastStep(); // Is the current step the last step
@@ -51,9 +53,13 @@ driverObj.refresh();
// Look at the configuration section for configuration options
// https://driverjs.com/docs/configuration#driver-configuration
driverObj.getConfig();
driverObj.setConfig({ /* ... */ });
driverObj.setConfig({
/* ... */
});
driverObj.setSteps([ /* ... */ ]); // Set the steps
driverObj.setSteps([
/* ... */
]); // Set the steps
// Look at the state section of configuration for format of the state
// https://driverjs.com/docs/configuration#state
@@ -61,9 +67,57 @@ driverObj.getState();
// Look at the DriveStep section of configuration for format of the step
// https://driverjs.com/docs/configuration/#drive-step-configuration
driverObj.highlight({ /* ... */ }); // Highlight an element
driverObj.highlight({
/* ... */
}); // Highlight an element
driverObj.destroy(); // Destroy the tour
```
> Each `driver()` call returns its own independent instance. You can create as many as you need on the same page, and their configuration, steps, and state never overlap.
> Each `driver()` call returns its own independent instance. You can create as many as you need on the same page, and their configuration, steps, and state never overlap.
## Hints
Hints ship as their own entry and factory. See the [Hints guide](/docs/hints) for an introduction, and the [Hints Configuration](/docs/configuration#hints-configuration) section for the options.
```javascript
import { hints } from "driver.js/hints";
import "driver.js/dist/hints.css";
// Look at the configuration section for the options
// https://driverjs.com/docs/configuration#hints-configuration
const productHints = hints({
/* ... */
});
// -----------------------------------------------------
// productHints is an object with the following methods
// -----------------------------------------------------
// Mount the beacons. Calling it again picks up hints
// whose elements have appeared since.
productHints.show();
// Remove the beacons and listeners; show() brings them back
productHints.hide();
// Hints are addressed by their `id`, or by their
// index in the array when no id is set.
productHints.open("export"); // Open a hint's popover
productHints.close(); // Close the open popover, keeping its beacon
productHints.dismiss("export"); // Remove the hint's beacon and fire onDismiss
productHints.restore("export"); // Bring a dismissed hint back
productHints.setHints([
/* ... */
]); // Replace the hints; resets dismissals
productHints.getHints(); // The configured hints
productHints.getActive(); // The hint whose popover is open, if any
productHints.isVisible(); // Whether the beacons are currently shown
// Reposition the beacons, the open popover and the
// overlay after layout changes
productHints.refresh();
```
> Like `driver()`, each `hints()` call is independent: its hints, dismissals, and overlay never affect another instance or a running tour.
apps/docs/src/content/guides/configuration.mdx
+161 -11
View File
@@ -48,7 +48,11 @@ type Config = {
overlayClickBehavior?:
| "close"
| "nextStep"
| ((element?: Element, step: DriveStep, options: { config: Config; state: State; driver: Driver; index: number | undefined }) => void);
| ((
element?: Element,
step: DriveStep,
options: { config: Config; state: State; driver: Driver; index: number | undefined }
) => void);
// Distance between the highlighted element and the cutout. (default: 10)
stagePadding?: number;
// Radius of the cutout around the highlighted element. (default: 5)
@@ -95,7 +99,10 @@ type Config = {
// PopoverDOM is an object with references to
// the popover DOM elements such as buttons
// title, descriptions, body, container etc.
onPopoverRender?: (popover: PopoverDOM, options: { config: Config; state: State; driver: Driver; index: number | undefined }) => void;
onPopoverRender?: (
popover: PopoverDOM,
options: { config: Config; state: State; driver: Driver; index: number | undefined }
) => void;
// Hooks to run before and after highlighting
// each step. Each hook receives the following
@@ -136,7 +143,11 @@ type Config = {
step: DriveStep,
options: { config: Config; state: State; driver: Driver; index: number | undefined }
) => void;
onDestroyed?: (element?: Element, step: DriveStep, options: { config: Config; state: State; driver: Driver; index: number | undefined }) => void;
onDestroyed?: (
element?: Element,
step: DriveStep,
options: { config: Config; state: State; driver: Driver; index: number | undefined }
) => void;
// Hooks to run on button clicks. Each hook receives
// the following parameters:
@@ -146,8 +157,16 @@ type Config = {
// - options.state: The current state of the driver
// - options.driver: Current driver object
// - options.index: Index of the currently active step
onNextClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State; driver: Driver; index: number | undefined }) => void;
onPrevClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State; driver: Driver; index: number | undefined }) => void;
onNextClick?: (
element?: Element,
step: DriveStep,
options: { config: Config; state: State; driver: Driver; index: number | undefined }
) => void;
onPrevClick?: (
element?: Element,
step: DriveStep,
options: { config: Config; state: State; driver: Driver; index: number | undefined }
) => void;
onCloseClick?: (
element?: Element,
step: DriveStep,
@@ -156,7 +175,11 @@ type Config = {
// Runs when the done button (the next button on the
// last step of a tour) is clicked. When provided, it
// runs instead of `onNextClick` on the last step.
onDoneClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State; driver: Driver; index: number | undefined }) => void;
onDoneClick?: (
element?: Element,
step: DriveStep,
options: { config: Config; state: State; driver: Driver; index: number | undefined }
) => void;
};
```
@@ -166,7 +189,7 @@ type Config = {
>
> `onNextClick` and `onPrevClick` hooks can be configured at the step level as well. When configured at the driver level, you control the navigation for all the steps. When configured at the step level, you control the navigation for that particular step only.
>
> `onDoneClick` lets you detect when the user finishes the tour by clicking the done button on the last step. When provided, it runs instead of `onNextClick` on the last step, and Driver.js won't destroy the tour automatically — you control teardown by calling `driverObj.destroy()` yourself. Like the other click hooks, it can be configured at the driver or step level.
> `onDoneClick` lets you detect when the user finishes the tour by clicking the done button on the last step. When provided, it runs instead of `onNextClick` on the last step, and Driver.js won't destroy the tour automatically; you control teardown by calling `driverObj.destroy()` yourself. Like the other click hooks, it can be configured at the driver or step level.
> `options.index`: Every hook receives the zero-based index of the currently active step in `options.index` (equivalent to `driverObj.getActiveIndex()`), or `undefined` when driving a single highlight rather than a `steps` array. Note that `index` always reflects the _active_ step, so inside `onDeselected` (which fires for the step being left during a transition) it points at the step being moved to, not the one being deselected.
@@ -228,7 +251,10 @@ type Popover = {
// Parameter is an object with references to
// the popover DOM elements such as buttons
// title, descriptions, body, etc.
onPopoverRender?: (popover: PopoverDOM, options: { config: Config; state: State; driver: Driver; index: number | undefined }) => void;
onPopoverRender?: (
popover: PopoverDOM,
options: { config: Config; state: State; driver: Driver; index: number | undefined }
) => void;
// Callbacks for button clicks. You can use
// these to add custom behavior to the buttons.
@@ -239,8 +265,16 @@ type Popover = {
// - options.state: The current state of the driver
// - options.driver: Current driver object
// - options.index: Index of the currently active step
onNextClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State; driver: Driver; index: number | undefined }) => void;
onPrevClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State; driver: Driver; index: number | undefined }) => void;
onNextClick?: (
element?: Element,
step: DriveStep,
options: { config: Config; state: State; driver: Driver; index: number | undefined }
) => void;
onPrevClick?: (
element?: Element,
step: DriveStep,
options: { config: Config; state: State; driver: Driver; index: number | undefined }
) => void;
onCloseClick?: (
element?: Element,
step: DriveStep,
@@ -248,7 +282,11 @@ type Popover = {
) => void;
// Runs instead of `onNextClick` when the done button
// (the next button on the last step) is clicked.
onDoneClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State; driver: Driver; index: number | undefined }) => void;
onDoneClick?: (
element?: Element,
step: DriveStep,
options: { config: Config; state: State; driver: Driver; index: number | undefined }
) => void;
};
```
@@ -306,6 +344,118 @@ type DriveStep = {
};
```
## Hints Configuration
Hints are configured through the `hints()` factory from the `driver.js/hints` entry. See the [Hints guide](/docs/hints) for an introduction and examples; the full options are given below.
```typescript
type HintsConfig = {
// Array of hints to show. See the Hint
// Configuration section below for the format.
hints?: DriverHint[];
// Beacon defaults applied to every hint;
// a hint's own beacon values win.
beacon?: HintBeacon;
// Text of the dismiss button. (default: "Got it")
buttonText?: string;
// Custom class and offset for the hint popovers,
// same meaning as in tours.
popoverClass?: string;
popoverOffset?: number;
// Dim the page while a hint is open, with the hint's
// element cut out like a tour step. The popover then
// anchors to the element instead of the beacon, the
// open hint's beacon steps aside, and the other
// beacons wait under the dim. Clicking the dimmed
// page closes the hint. (default: false)
overlay?: boolean;
// Color and opacity of the dim. (defaults: "#000" and 0.7)
overlayColor?: string;
overlayOpacity?: number;
// Called when a hint popover is opened, and when a
// hint is dismissed (via the button or `dismiss()`).
// Each hook receives the following parameters:
// - element: The hint's target DOM element
// - hint: The hint object
// - options.config: The hints configuration
// - options.hints: The hints instance
onOpen?: (element: Element, hint: DriverHint, options: { config: HintsConfig; hints: Hints }) => void;
onDismiss?: (element: Element, hint: DriverHint, options: { config: HintsConfig; hints: Hints }) => void;
};
```
## Hint Configuration
Each entry of the `hints` array describes one hint: the element it points at, the beacon that sits on it, and the popover that opens on click.
```typescript
type DriverHint = {
// The element the hint points at. This can be a DOM
// element, a function that returns a DOM element, or
// a CSS selector. A hint whose element is missing is
// skipped, and picked up on the next show() if the
// element has appeared since.
element: Element | string | (() => Element);
// Stable identity used by open/dismiss/restore and
// passed to the hooks; useful for persisting
// dismissals. Defaults to the hint's index.
id?: string;
// Where the beacon sits on the element's box, and
// how it looks.
beacon?: {
// Edge of the element the beacon sits on. (default: "top")
side?: "top" | "right" | "bottom" | "left";
// Position along that edge. (default: "end")
align?: "start" | "center" | "end";
// Whether the beacon pulses. The pulse also pauses
// automatically for users who prefer reduced
// motion. (default: true)
animate?: boolean;
// Custom class for the beacon, e.g. to scope the
// --driver-hint-size and --driver-hint-color
// CSS variables to it.
className?: string;
};
// The popover that opens when the beacon is clicked.
// Rendered exactly like a tour popover.
popover?: {
title?: string;
description?: string;
side?: "top" | "right" | "bottom" | "left";
align?: "start" | "center" | "end";
popoverClass?: string;
// The dismiss button. Hide it for hints you only
// dismiss from code. (default: true)
showButton?: boolean;
// Overrides the instance-level buttonText.
buttonText?: string;
// Hook to run after the popover is rendered,
// same as in tours but with the hint and the
// hints instance in the options.
onPopoverRender?: (popover: PopoverDOM, options: { hint: DriverHint; hints: Hints }) => void;
};
// Hint-level hooks, taking precedence over the
// instance-level ones.
onOpen?: (element: Element, hint: DriverHint, options: { config: HintsConfig; hints: Hints }) => void;
onDismiss?: (element: Element, hint: DriverHint, options: { config: HintsConfig; hints: Hints }) => void;
// Arbitrary data to carry along, available wherever
// the hint object is.
data?: Record<string, any>;
};
```
## State
You can access the current state of the driver by calling the `getState` method. It's also passed to the hooks and callbacks.