New in V3

Everything new and improved in React Joyride V3.

Upgrading from V2? See the Migration Guide for breaking changes.

New Features

useJoyride Hook

The useJoyride() hook is the core API. It returns tour controls, state, the current step, step failures, and event subscriptions as explicit values — making it easy to coordinate the tour with your app's UI and state.

tip

The <Joyride /> component is a convenience wrapper around the hook. Both accept the same props.

Event System

The onEvent callback receives discriminated event types (tour:start, step:before, tooltip, etc.) and a controls object as the second argument. Subscribe to specific events with the on() method instead of filtering in a callback.

Step Hooks

Run async logic before a step with before or fire-and-forget cleanup with after.

tip

While before is resolving, the tour shows a loader (after loaderDelay ms). You can customize or disable the loader with loaderComponent.

Separate Scroll & Spotlight Targets

scrollTarget scrolls to a different element than the tooltip target, and spotlightTarget highlights a different element. The tooltip still anchors to target. Useful for highlighting a container while pointing at a specific child, or scrolling a parent into view.

Floating UI

Tooltip positioning uses @floating-ui/react-dom directly, replacing Popper.js/react-floater. Configure middleware, flip/shift behavior, positioning strategy, and beacon offset via floatingOptions.

Custom Components

arrowComponent and loaderComponent join the existing beacon and tooltip overrides. Set loaderComponent to null to disable the loader entirely.

Portal Rendering

All tour UI renders via a React portal. Use the portalElement prop to target a custom container instead of document.body.

initialStepIndex

Start uncontrolled tours at any step with initialStepIndex. Previously, tours always started at step 0.

React 19 Support

Full compatibility with React 16.8 through React 19.

Improvements

Interaction Control

Overlay clicks, ESC key, and the close button used to be on/off only. Now they support actions:

Focus Trap

Now a proper hook with per-step control via disableFocusTrap. Focus is restored to the previously active element when the tooltip closes.

Target Resolution

target now accepts RefObject<HTMLElement> and () => HTMLElement | null in addition to CSS selectors and elements. The tour polls for missing targets up to targetWaitTimeout ms before advancing.

Options System

All options are now flat fields that can be set globally via the options prop or overridden directly on any step. Merge priority: defaults → options prop → step fields.

SVG Overlay

The overlay uses an SVG path cutout instead of CSS box-shadow, providing precise spotlight rendering with configurable spotlightRadius.

Spotlight Padding

spotlightPadding now accepts a { top, right, bottom, left } object for per-side control, in addition to a single number.

Buttons

Individual hideBackButton, hideCloseButton, and showSkipButton props are replaced by a single buttons array: ['back', 'close', 'primary', 'skip'].

Smaller Bundle

~30% smaller than V2. Replaced react-floater, deepmerge, and tree-changes with lighter alternatives and local implementations.

Bug Fixes

info

These were among the most-reported issues in V2.

  • Live target tracking — The spotlight and tooltip follow targets that move, resize, or live inside scroll containers.
  • Fixed-position spotlight — Correct rendering when the target has fixed or sticky ancestors.
  • Spotlight clicks in scroll containers — Click-through now works regardless of scroll position.
  • Touch device interaction — No more double-tap required on mobile.