Registry /
web-framework / react-router-dom-v5-compat
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CompatRouter
✓ import { BrowserRouter as CompatRouter } from 'react-router-dom-v5-compat';
✗ import { CompatRouter } from 'react-router-dom-v5-compat'; // Incorrect alias
This package re-exports the v5 `BrowserRouter` as `CompatRouter` to be used within a v6 application. You typically import it as an alias.
CompatSwitch
✓ import { Switch as CompatSwitch } from 'react-router-dom-v5-compat';
✗ import { CompatSwitch } from 'react-router-dom-v5-compat'; // Incorrect alias
Re-exports the v5 `Switch` component, which is crucial for v5 route matching logic. `Switch` was removed in v6.
useCompatHistory
✓ import { useHistory as useCompatHistory } from 'react-router-dom-v5-compat';
✗ import { useHistory } from 'react-router-dom-v5-compat'; // Ambiguous with v6's useNavigate
Re-exports the v5 `useHistory` hook. In v6, `useNavigate` is the successor, so using the aliased `useCompatHistory` makes it clear you're using the v5 equivalent.
Demonstrates how to integrate v5-style components and hooks using `react-router-dom-v5-compat` within a v6 `react-router-dom` application, allowing for a phased migration.
import React from 'react';
import ReactDOM from 'react-dom/client';
import { BrowserRouter as Router, Routes, Route, Link } from 'react-router-dom';
import { BrowserRouter as CompatRouter, Switch as CompatSwitch, useHistory as useCompatHistory } from 'react-router-dom-v5-compat';
// A v5-style component
function OldHomePage() {
const history = useCompatHistory();
const handleClick = () => {
history.push('/old-about');
};
return (
<div>
<h2>Old Home Page (v5 compat)</h2>
<button onClick={handleClick}>Go to Old About</button>
<Link to="/v6-dashboard">Go to v6 Dashboard</Link>
</div>
);
}
// Another v5-style component
function OldAboutPage() {
return <h2>Old About Page (v5 compat)</h2>;
}
// A v6-style component
function V6Dashboard() {
return <h2>V6 Dashboard</h2>;
}
function App() {
return (
<Router>
<h1>Mixed React Router App</h1>
<Routes>
{/* v6 routes */}
<Route path="/v6-dashboard" element={<V6Dashboard />} />
<Route path="/" element={
<CompatRouter>
{/* v5 compatibility routes inside CompatRouter */}
<CompatSwitch>
<CompatRoute path="/old-about" component={OldAboutPage} />
<CompatRoute path="/" component={OldHomePage} />
</CompatSwitch>
</CompatRouter>
} />
</Routes>
</Router>
);
}
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);
Errors
Common errors & fixes
Error: Invalid hook call. Hooks can only be called inside of the body of a function component.
Attempting to use `useCompatHistory` or other `useCompat` hooks outside of a component rendered within a `CompatRouter` context.
fixEnsure that any component using `useCompatHistory` or similar compatibility hooks is a child of `CompatRouter` (or `BrowserRouter as CompatRouter`).
Error: No routes matched location "/path"
This often indicates a mismatch between v5 and v6 routing configurations. For example, a v5 `CompatRoute` inside a v6 `Routes` without being nested in a `CompatSwitch` or `CompatRouter` that interprets v5 routes.
fixVerify that v5 compatibility routes are correctly nested within `CompatRouter` and `CompatSwitch` components, and that the `path` props align with v5's exact/non-exact matching rules.
TypeError: Cannot read properties of undefined (reading 'push')
Likely attempting to access `history.push` from `useCompatHistory` before the history object is properly initialized by the `CompatRouter` or outside its scope.
fixConfirm that the component calling `useCompatHistory` is rendered within the component tree established by `CompatRouter`.
Audit
Dependencies
reactrequiredPeer dependency for React applications.
react-domrequiredPeer dependency for React DOM rendering.
react-router-domrequiredRequires `react-router-dom` v4 or v5 installed alongside v6 to provide the necessary legacy context and components for the compatibility layer.