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
waitForRemovedElementsets how long a removed element gets to come back, separately fromwaitForElement. Both takeInfinity.scrollIntoViewtakes{ block, inline }to say where the element ends up.allowPageInteractionlets the user use the whole page during a step.focusputs the keyboard on the popover, in the highlighted element, or leaves it where it is.- In the headless build,
onInteractionreports clicks onallowedElementsasregion: "allowed". onPopoverPositionedruns 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.
onDestroyedruns when the tour is closed before the first step has settled.- A
waitForElementlonger than about 24 days no longer runs out at once.
1.13.0
Added
driver.js/headlessruns a tour without drawing anything, so you can render your own UI.scrollIntoView: falsestops driver.js from scrolling to the highlighted element and popover.onWaitingForElementtells you when a step starts waiting for its element, and itssignalwhen the wait ends.onElementReplacedtells 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: noneinside the highlighted element is no longer overridden.
1.12.0
Added
popover.instructionmakes 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.advanceDelaypauses on a completed step before moving on. Action steps show a done state meanwhile.driverObj.advance()completes the current step from your code, likeadvanceOndoes.driverObj.nudge("message")shows a line of feedback in the popover and shakes it.onElementMissingtakes"stay","previous"or"previousAction"as well as a function.disableActiveInteraction: "clicks"blocks clicks on the highlighted element but keeps hover working.onHighlightStartedgets the samesignalasonHighlighted.- A console warning when
disableActiveInteractionmakes a step’sadvanceOnimpossible. - 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’sdocumentandbodylisteners. UseonInteractionto see them. disableActiveInteraction: truealso 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.onDestroyStartedgets the step being entered when the tour is closed during its first animation, notundefined.- The
Statetype 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()anddestroy()now work when called fromonHighlightStarted,onHighlightedoronDeselected.moveTo()starts the tour if it isn’t running.setSteps()on a running tour ends it cleanly. Calldrive()to start the new steps.- A step’s
showProgress: falsenow wins overshowProgress: trueon the driver. - A fast double-click no longer skips a step that advances on click.
advanceOnClickignores 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 whenonDestroyStartedis set.- Less layout work while scrolling with hints or a tour, and
waitForElementchecks the page at most once a frame.
1.11.0
Added
advanceOncompletes a step on any event, like"contextmenu", and{ event, when }only completes it when your check passes.onInteractionsees clicks, right-clicks and double-clicks during a step and can block them withreturn false.allowedElementskeeps menus and popups opened by a step usable above the overlay.onElementMissinglets you recover when a step’s element disappears or a wait times out. Returnfalseon 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, andnudge({ description })changes its text at the same time.onHighlightedgets asignalthat aborts when the step is left.
Changed
- While
waitForElementwaits, 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-expandedoraria-controls. advanceOnClickis deprecated in favor ofadvanceOn: "click". It keeps working.- The tour ignores Escape and arrow keys whose
keydownyour 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 atransformorfilternow 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 ofheaderandfooterlandmarks, and the centered dummy element gets no aria attributes. (#434)
1.10.1
Added
launcher: falseon checklists drops the floating launcher, for pages that open the panel from their own button withopen()ortoggle(). 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 withshowModal()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/checklistentry (withdist/checklist.css). Items start a tour, follow a link or run an action, and are ticked when the user finishes the tour, or bycompleteWhenandcomplete(), or by the user withallowManualComplete. Progress comes in throughcompletedand goes out throughonProgress;onEventreports 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. reasonin the options ofonDestroyStarted,onDestroyedand theonDeselectedthat 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"). Adestroy()called from a hook keeps the reason of the user action that started it. TheDestroyReasonandHookOptstypes 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’saria-label, for translated tours. Defaults toClose. (#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
waitForElementwaits 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
onDeselectedandonDestroyedbut notonDestroyStarted.
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-expandedandaria-haspopupare 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)
onDeselectednow fires when moving between two steps on the same element, or between two steps without an element.- The driver-level
disableButtonsnow applies to tour steps. It used to be ignored during a tour. A step’s owndisableButtonsstill 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)sideEffectsfield 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 runsonDoneClick; step queries likeisLastStep()account for skips. (#616)
1.7.0
Added
skipMissingElementoption (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)indexon the options passed to every hook, holding the currently active step index (same value asdriverObj.getActiveIndex()). (#490)--driver-popover-font-familyCSS 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 defaultsans-serif. An internal rule had been shadowing the intended font. Set--driver-popover-font-familyto 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
animationDurationconfig to control how long the highlight transition takes. (#104)allowScrollconfig to lock body scroll while a tour is active.onDoneClickhook, fired when the done button on the final step is clicked. (#500)dataproperty 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-btnclass instead of the.driver-popover-footer buttonselector. Buttons you add throughonPopoverRenderno longer inherit the default styling automatically. Add thedriver-popover-footer-btnclass 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
onPopoverRendernow 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-*anddriver-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
onDriverClickthat 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)
removeChildDOMException 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, respectingallowCloseand any customonCloseClick. (#444)
1.5.0
Added
getNextStepmethod on the driver API. (#420)driver-popover-done-btnclass on the next button when it acts as the done button on the final step. (#610)
Changed
- The
onDestroyedhook 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)
onNextClicknow 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.
driver.js