Changelog

Unreleased lists what is merged for the next release.

Unreleased

Fixed

  • Tab no longer gets stuck on hidden or inert controls inside the highlighted element. (#631)

1.14.0

Added

  • waitForRemovedElement sets how long a removed element gets to come back, separately from waitForElement. Both take Infinity.
  • scrollIntoView takes { block, inline } to say where the element ends up.
  • allowPageInteraction lets the user use the whole page during a step.
  • focus puts the keyboard on the popover, in the highlighted element, or leaves it where it is.
  • In the headless build, onInteraction reports clicks on allowedElements as region: "allowed".
  • onPopoverPositioned runs every time the popover is placed, so you can move it somewhere else and keep it there.

Changed

  • The cutout and popover only cover the part of the element in view, so a row wider than its scrolling panel is highlighted inside the panel.
  • The popover scrolls into view only as far as it needs to, so it no longer undoes where the element was scrolled to.
  • When the tour ends, the keyboard goes back where it was only if it is still on the popover.

Fixed

  • The highlight follows a panel that scrolls inside the page.
  • onDestroyed runs when the tour is closed before the first step has settled.
  • A waitForElement longer than about 24 days no longer runs out at once.

1.13.0

Added

  • driver.js/headless runs a tour without drawing anything, so you can render your own UI.
  • scrollIntoView: false stops driver.js from scrolling to the highlighted element and popover.
  • onWaitingForElement tells you when a step starts waiting for its element, and its signal when the wait ends.
  • onElementReplaced tells you when the app re-renders the highlighted element and the step moves to the new one.

1.12.1

Changed

  • A new popover focuses Next instead of the close button, so Enter no longer ends the tour.
  • Your CSS can hide or restyle popover parts without !important.

Fixed

  • The popover shows above a dialog that opens mid-step instead of behind it.
  • pointer-events: none inside the highlighted element is no longer overridden.

1.12.0

Added

  • popover.instruction makes a step an action step: the user has to do what it says. Next looks disabled until they do.
  • advanceOn: { event, strict: true } lets only that gesture through on the highlighted element.
  • advanceDelay pauses on a completed step before moving on. Action steps show a done state meanwhile.
  • driverObj.advance() completes the current step from your code, like advanceOn does.
  • driverObj.nudge("message") shows a line of feedback in the popover and shakes it.
  • onElementMissing takes "stay", "previous" or "previousAction" as well as a function.
  • disableActiveInteraction: "clicks" blocks clicks on the highlighted element but keeps hover working.
  • onHighlightStarted gets the same signal as onHighlighted.
  • A console warning when disableActiveInteraction makes a step’s advanceOn impossible.
  • A highlighted element inside an allowed element, like an item in an open menu, gets a ring instead of a hidden cutout.
  • CSS variables for the instruction row, the feedback line and that ring. See Theming.

Changed

  • Clicks on the padding around the highlighted element, or on an element with disableActiveInteraction, no longer reach your app’s document and body listeners. Use onInteraction to see them.
  • disableActiveInteraction: true also blocks Enter and Space on the highlighted element.
  • A highlighted element that your framework re-renders is followed automatically.
  • overlayClickBehavior: "nextStep" does nothing while the popover waits for an element.
  • onDestroyStarted gets the step being entered when the tour is closed during its first animation, not undefined.
  • The State type no longer lists the internal __ keys added in 1.11.0.

Fixed

  • Steps inside a modal <dialog> now dim the dialog and cut out the highlighted element.
  • moveNext(), drive() and destroy() now work when called from onHighlightStarted, onHighlighted or onDeselected.
  • moveTo() starts the tour if it isn’t running.
  • setSteps() on a running tour ends it cleanly. Call drive() to start the new steps.
  • A step’s showProgress: false now wins over showProgress: true on the driver.
  • A fast double-click no longer skips a step that advances on click. advanceOnClick ignores clicks while a step animates in, as before 1.11.0.
  • The key that completes a step, like Enter, no longer presses a button in the next popover.
  • The highlight and popover stay on their element when it changes size, when a framework rewrites its className, and when the page resizes mid-step.
  • A highlighted element that is removed from the page no longer keeps driver.js classes and aria attributes.
  • drive() without steps no longer locks the page when onDestroyStarted is set.
  • Less layout work while scrolling with hints or a tour, and waitForElement checks the page at most once a frame.

1.11.0

Added

  • advanceOn completes a step on any event, like "contextmenu", and { event, when } only completes it when your check passes.
  • onInteraction sees clicks, right-clicks and double-clicks during a step and can block them with return false.
  • allowedElements keeps menus and popups opened by a step usable above the overlay.
  • onElementMissing lets you recover when a step’s element disappears or a wait times out. Return false on a timeout to stay on the current step.
  • driverObj.updatePopover() changes the popover text in place and announces it to screen readers.
  • driverObj.nudge() shakes the popover to draw attention, and nudge({ description }) changes its text at the same time.
  • onHighlighted gets a signal that aborts when the step is left.

Changed

  • While waitForElement waits, the popover stays visible in a waiting state, keeping the close button usable.
  • Escape and arrow keys pressed in a text field, select or ARIA widget inside the highlighted element now go to your app instead of the tour.
  • The popover no longer takes focus from the highlighted element when a step starts.
  • showButtons: [] in the driver config now hides all buttons instead of showing all of them.
  • Highlighting no longer overwrites an element’s own aria-haspopup, aria-expanded or aria-controls.
  • advanceOnClick is deprecated in favor of advanceOn: "click". It keeps working.
  • The tour ignores Escape and arrow keys whose keydown your app prevented or stopped.

Fixed

  • Hints in an open <dialog> no longer get covered when the page styles every [popover], for example with a dark background. (#628)

1.10.2

Fixed

  • Hints and popovers in an open <dialog> with a transform or filter now stay next to their element, also after the dialog reopens. (#627)
  • Tour steps scrolled out of a visible scrollable container are now scrolled into view. (#577)
  • The popover title and footer are divs instead of header and footer landmarks, and the centered dummy element gets no aria attributes. (#434)

1.10.1

Added

  • launcher: false on checklists drops the floating launcher, for pages that open the panel from their own button with open() or toggle(). Closing the panel hands focus back to whatever opened it.

Fixed

  • Hints, and popovers of tour steps, whose element is inside an open <dialog> now render inside that dialog, so they show above a modal opened with showModal() instead of behind it. (#625)
  • Clicking the popover no longer throws when the event’s target is a text node. (#626)

1.10.0

Added

  • Checklists: an onboarding widget in its own driver.js/checklist entry (with dist/checklist.css). Items start a tour, follow a link or run an action, and are ticked when the user finishes the tour, or by completeWhen and complete(), or by the user with allowManualComplete. Progress comes in through completed and goes out through onProgress; onEvent reports everything for analytics. It sits in any corner of the screen (position, offset), adapts to phones, and can show a different title and launcher text once everything is done. See the Checklists guide, and Checklist Themes for ready-made themes.
  • reason in the options of onDestroyStarted, onDestroyed and the onDeselected that runs on destroy, telling apart a finished tour ("done") from one that was closed ("close", "escape", "overlay"), replaced by another instance ("replaced") or ended from code ("api"). A destroy() called from a hook keeps the reason of the user action that started it. The DestroyReason and HookOpts types are exported.

Changed

  • The popover’s close button only darkens for keyboard focus (:focus-visible), so it no longer opens dark after a tour is started with a mouse click.

1.9.0

Added

  • closeBtnLabel (driver and step level) to set the close button’s aria-label, for translated tours. Defaults to Close. (#623)
  • overlayClickBehavior: "none" to ignore overlay clicks while Escape and the close button still close the tour. (#435)

Changed

  • Keyboard control follows the popover buttons: arrow keys do nothing when their button is hidden or disabled, and Escape does nothing when the close button is disabled. (#589)
  • The current popover is hidden while waitForElement waits for the next step’s element, so a stale step no longer stays on screen. (#578)
  • Only one instance is on screen at a time. Starting a tour or highlight closes any other active instance; it gets onDeselected and onDestroyed but not onDestroyStarted.

Fixed

  • destroy() on an instance that is not active is now a no-op instead of tearing down another instance’s tour. (#504)
  • The highlighted element’s own aria-controls, aria-expanded and aria-haspopup are restored when the highlight moves on or the tour ends, instead of being removed. (#495)
  • No more small white square between steps without an element. (#549)
  • onDeselected now fires when moving between two steps on the same element, or between two steps without an element.
  • The driver-level disableButtons now applies to tour steps. It used to be ignored during a tour. A step’s own disableButtons still replaces it.

1.8.0

Added

  • Hints: pulsing beacons that open a popover on click; overlay optional, the page stays interactive. driver.js/hints, ~5KB gzip. Guide. (#363)
  • advanceOnClick (driver and step level) to advance the tour by clicking the highlighted element itself. (#606)
  • waitForElement (driver and step level) to wait up to N ms for a step’s element before treating it as missing. (#606)
  • sideEffects field in package.json for better tree-shaking.

Changed

  • Popover internals shared between tours and hints; tour behaviour verified unchanged against 1.7.0.
  • Build migrated from vite to tsdown; artifact names, exports map and CDN globals unchanged, sizes within ±2%.

Fixed

  • skipMissingElement: the last reachable step now shows Done and runs onDoneClick; step queries like isLastStep() account for skips. (#616)

1.7.0

Added

  • skipMissingElement option (driver and step level) to skip a step whose target element is specified but not in the DOM, instead of showing the centered fallback popover. Element-less steps are never skipped. (#489, #395)
  • index on the options passed to every hook, holding the currently active step index (same value as driverObj.getActiveIndex()). (#490)
  • --driver-popover-font-family CSS variable to set the popover font in one place, without overriding each text element individually. (#607)

Changed

  • The popover title and description now render in the default font stack ("Helvetica Neue", …) instead of the browser’s default sans-serif. An internal rule had been shadowing the intended font. Set --driver-popover-font-family to use your own.

Fixed

  • Icon fonts (Material Icons, Font Awesome, etc.) placed inside a step description are no longer overridden by the popover font and render correctly. (#510, #512)
  • Each driver() call keeps its own config, steps and state, so creating a second instance no longer overwrites the first. (#571)
  • Popover no longer jumps when its content has images that load after render.

1.6.0

Added

  • animationDuration config to control how long the highlight transition takes. (#104)
  • allowScroll config to lock body scroll while a tour is active.
  • onDoneClick hook, fired when the done button on the final step is clicked. (#500)
  • data property on a step for passing arbitrary data, accessible from hooks for custom per-step logic. (#539)

Changed

  • Breaking Popover footer buttons are now styled through the driver-popover-footer-btn class instead of the .driver-popover-footer button selector. Buttons you add through onPopoverRender no longer inherit the default styling automatically. Add the driver-popover-footer-btn class to opt in, or leave it off to apply your own styles. The built-in next/previous buttons carry the class out of the box. (#555)
  • Custom buttons added through onPopoverRender now receive their own click events. Only the built-in next, previous, and close buttons have their default action intercepted by the library.
  • The popover exposes driver-popover-side-* and driver-popover-align-* classes so you can target its position from CSS, and the arrow positioning was rewritten for more accurate placement.

Fixed

  • Document event listener leak in onDriverClick that left handlers attached after the tour was destroyed. (#452)
  • Dropped the CSS :has() selector for broader browser compatibility. (#586)
  • Positioned highlighted elements and their children (e.g. dropdown menus) no longer get clipped. (#454, #563)
  • removeChild DOMException when re-rendering a popover whose wrapper was already detached from the DOM. (#572)
  • Close button on a single-element highlight() popover did nothing when clicked. It now closes the popover by default, respecting allowClose and any custom onCloseClick. (#444)

1.5.0

Added

  • getNextStep method on the driver API. (#420)
  • driver-popover-done-btn class on the next button when it acts as the done button on the final step. (#610)

Changed

  • The onDestroyed hook now receives the final tour state. (#553)
  • Removed the unicode characters from the default button labels.

Fixed

  • The tour no longer closes when pressing the left arrow on the first step. (#564)
  • Removed the button text-shadow that left ghost text behind. (#605)
  • onNextClick now fires when advancing the tour through an overlay click. (#576)

For the release notes of other versions, see the GitHub releases page.

Migrating from 0.x to 1.x

See Migrate to 1.x for the import, configuration and API changes.