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

For a complete list of changes, check the PR.

We'd love your feedback! If you run into issues, have questions about migrating, or want to share ideas, join the discussion: #1196