React Joyride V3

[gilbarbara]

V3 is a complete rewrite focused on modern React patterns, smaller bundle size, and a more intuitive API.

Highlights

• useJoyride hook — replaces getHelpers with a proper hook returning controls, state, current step, failures, and event subscriptions
• New event system — discriminated event types (tour:start, step:before, tooltip, etc.) with onEvent(data, controls) and selective subscription via on()
• Step hooks — async before/after callbacks for per-step logic
• Floating UI — replaced Popper.js/react-floater with direct @floating-ui/react-dom integration
• Flexible targets — scrollTarget and spotlightTarget for independent positioning; targets accept RefObject, callbacks, and CSS selectors
• SVG overlay — precise spotlight rendering replacing CSS box-shadow
• Portal rendering — tour UI renders via React portal with custom container support
• New component props — arrowComponent, loaderComponent
• React 16.8–19 support
• ~30% smaller bundle through dependency replacement

Breaking changes

• Named export: import { Joyride } from 'react-joyride'
• callback replaced by onEvent prop
• run defaults to false
• getHelpers replaced by useJoyride() hook
• Step-level props consolidated into flat options (set globally or per-step)
• styles.options theming moved to options prop
• Button visibility via buttons array (['back', 'close', 'primary'])
• Multiple prop renames (disableBeacon → skipBeacon, disableCloseOnEsc → dismissKeyAction, floaterProps → floatingOptions, etc.)
• Removed: disableScrollParentFix, styles.spotlight, legacy overlay styles

Full migration guide: https://react-joyride.com/docs/migration
What's new: https://react-joyride.com/docs/new-in-v3

[gadgetgourmet]

What a coincidence! I was exploring Joyride and wasn't sure whether I should use v2 or the various beta's of v3, reluctantly decided to try v3 since I'm on React 19, and just found that 3.0.0 is officially released. So far so good. No problems. Thank you so much!!!

[gilbarbara]

The final V3 is much more stable and mature than previous versions. Glad it helped you!

[thisdotgrace]

Loving many of the new features in v3 - great work! One thing I’m confused about is the removal of the event step prop. That made it very easy to advance the tour when a user interacted with a UI element without having to modify that component.

The new target: componentRef examples in the controlled demo are great but in my app I can’t change the components I need to detect. The tour is multi route and controlled centrally via a provider and context, so the v2 event worked really well.

Is there a recommended pattern in v3 for achieving a similar click target to advance flow without touching the underlying component. Would love more insight into the thinking behind this, apologies if I’ve missed something obvious. I’m a junior developer, still working on my key understanding.

Thanks again for the great work!

[gilbarbara]

Hey @thisdotgrace

Thanks for the kind words!

I think there might be some confusion here. The callback prop was renamed to onEvent in v3, but it still receives all the same step data (step, action, type, index, etc.).

You don't need to use refs as targets — string selectors like target: '.my-element' still work exactly as before. The ref examples in the controlled demo are just one option.

The onEvent signature in v3 actually makes controlled tours easier with a new controls second argument:

onEvent(data, controls) {
  // data.step, data.type, data.index, etc.
  // controls.next(), controls.prev(), controls.go(index), etc.
}

So your centralized provider pattern should work the same way — just rename callback to onEvent and you're good to go.

Check the events docs for the full API.

Let me know if you were referring to something else, and I'll help sort it out!

[thisdotgrace]

Sorry I’m referring to in the Steps props, previously you could specify: event: ‘click’ and then that would require the user to click the highlighted target to progress.

[gilbarbara]

Not really, event was just used for the Beacon, and it's still there as beaconTrigger.
You can read more about the changes in the Migration docs.

This library never interacts directly with any element of your app; it only allows clicks to pass through the overlay/spotlight.