Documentation
Installation, API lifecycles, transition options, and copyable React Router examples for Routeveil.
Installation
npm install routeveil
Import Routeveil for React Router from routeveil/react-router.
Compatibility
Supported versions
| Dependency | Range |
|---|
| React | ^18.0.0 || ^19.0.0 |
| React DOM | ^18.0.0 || ^19.0.0 |
| React Router DOM | ^6.27.0 || ^7.0.0 |
Routeveil is tested in CI across React 18 and 19 with supported React Router DOM 6 and 7 releases.
React Router 5 and React Router 8 are not currently supported. View the exact test matrix.
Interrupted Navigation
Routeveil runs one transition and one active promise at a time. Additional Routeveil navigation and playback requests reuse that promise without queueing or committing another destination.
Browser history and other external location changes cancel current visual work, leave the latest location in control, preserve meaningful application focus or focus the incoming RouteveilView with preventScroll, and clean up animations, inert state, temporary attributes, overlays, timers, location waiters, and transition phase.
Shared Elements
RouteveilSharedElement connects matching real HTML or SVG elements across routes by a unique name without adding a layout wrapper.
Shared elements compose with page transitions in a strict sequence: page exit → shared-element movement → page enter. They are not transitions named shared or shared-element. Multiple valid matches move concurrently, different tags crossfade, and each settled clone stays over its hidden real target until page enter completes. Missing or duplicate targets are skipped without blocking navigation.
Use scrollToSharedElement with an exact incoming shared-element name to center it vertically while preserving horizontal scroll before endpoint measurement. URL hashes take precedence; valid anchors override preventScrollReset and smoothScrollToTop, while missing or duplicate anchors warn and fall back to the existing scroll policy. Reduced-motion navigation still applies valid anchor positioning.
Overlay transitions, same-page playback, browser-history navigation, and reduced-motion navigation do not run shared-element movement.
Open the shared elements playground