• controls.replay(origin?) — re-run current step. Re-emits step:after → step:before, re-runs before/after hooks, index unchanged. Only valid from RUNNING + TOOLTIP.
• New 'replay' value for closeButtonAction, dismissKeyAction, overlayClickAction. Dismiss tooltip → show beacon on same step (resolves #1205).
• New ACTIONS.REPLAY literal.

• Floater zIndex offset reduced (+100 → +1). Relative stacking with overlay unchanged.

Parent onEvent must skip index increment on STEP_AFTER + ACTIONS.REPLAY:

if (type === EVENTS.STEP_AFTER && action === ACTIONS.REPLAY) return;

• New recipe: Conditional / Dynamic Steps — use before hooks, not useEffect-driven stepIndex.
• Controlled mode: "use sparingly" guidance.
• Updated ControlsTable, OptionsTable, exports reference, and architecture doc.

Full Changelog: https://github.com/gilbarbara/react-joyride/compare/v3.0.2...v3.1.0

• Fix React 18 aggressive batching: 79a7ef0d9e8f0e1a96631a34275c59a07ed5fcc7
• Re-organize modules: 324b5c92c91387288c108deac0cdbcb0a98d8de9
• Propagate origin through all UI-triggered control methods: ee6aad34a01e4b50c0608a12ec16f08132a6cc9c

• Upgrade dependencies: 2199f9eebb76f128858260a9258fdeeabf08539e
• Add support to spotlight styles (SVGPath): 40e6faae78117a65350f6823b8070ce9249d12d6

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

• 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

• 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: https://github.com/gilbarbara/react-joyride/discussions/1196

• Update custom-components docs: 650ab36b1cd4a48b4867bce9a94523324c4cc9e4
• Upgrade dependencies: 987415098c53af59faaec8ac4404de25601d7978
• Fix scroll for targets with custom scroll parent or fixed position: 3648311d664498214ef9ef00752f8b1254641777
• Disable tooltip keyboard focus if the disableScrolling is set: af6fa9eae16e4edf5372323768b354d2a1012770
• Fix locale handling of custom components: 826669d18f32c8ae3cbd5ef92188a017c13c764f

• Fix primary button text with showProgress: 58ecae0dd400f7ba6d6241c13d35e133a4cea772
• Fix lifecycle for centered steps: 8ee561ac62b6a4e9fea03ef406f92325c0d96afe
• Fix docs and types: 6bf66cac3c140f88ed38df3eddc8ffb9c9ad058b

• Remove duplicate store update for placement "center": 9bac425acf567d4ce4ac1181447cbe1fdc49c0ab

• Upgrade dependencies: 76b0eaebe35a7a8226e60a89e530d95bfb5e18ef
• Add try/catch to getElement helper: 92e204d7fcf62c235c15460d6cff133b1125dc3e
• Add LIFECYCLE.INIT to Overlay "hideSpotlight": e4a75a455203d4c0e6b875dd828cd20809e26e0c
• Add "nextLabelWithProgress" to step locale: 0fbf34662833460e8a016acac9bd7cb3c5246781
• Update "getDocumentHeight" median parameter default to false: d7febf7efa5895a1827642ff403ca3bbb99ccad4
• Fix types and defaults: 805356cfd76a58aaf2f13c1f2d41a4ce7cc5457c

• Upgrade dependencies: 0b4912fd0579b4317190c7c2a9ba7e2da464f9f9
• Update GH Actions workflow: 7327b2ccabd7021a961b04828c476cca6ef83fcc
• Hide the Beacon for centered steps or disableBeacon: 8fc34dff633db6e0ca1aa4db05403030404b63b7

• Replace @gilbarbara/helpers with local utils: 84f8b240135c32d3b2247d9d4c0022d262680e76
• Upgrade dependencies: 7f078e3e5caa09e8d418d5e09e1a49604bbfd3ca
• Add optional "data" to step: d6d6eaa84ff74dfb8de46ce63433bff6fe36e6dc