{"id":15213,"library":"react-router-dom-v5-compat","title":"React Router v5 Compatibility Layer","description":"The `react-router-dom-v5-compat` package provides a migration path for applications transitioning from React Router v4 or v5 to v6. It offers compatibility components and hooks that allow developers to run existing v5 routing logic within a v6 application environment. This enables incremental upgrades, avoiding a \"big bang\" rewrite. The package's current stable version is 6.30.3, aligning with the `react-router@6.x` series. While the core `react-router` project has progressed to v7, this compatibility layer remains focused on facilitating the v5-to-v6 migration. Its primary differentiator is enabling the co-existence of v5 and v6 routing paradigms, providing a temporary bridge rather than a permanent solution.","status":"maintenance","version":"6.30.3","language":"javascript","source_language":"en","source_url":"https://github.com/remix-run/react-router","tags":["javascript","react","router","route","routing","history","link","typescript"],"install":[{"cmd":"npm install react-router-dom-v5-compat","lang":"bash","label":"npm"},{"cmd":"yarn add react-router-dom-v5-compat","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-router-dom-v5-compat","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React applications.","package":"react","optional":false},{"reason":"Peer dependency for React DOM rendering.","package":"react-dom","optional":false},{"reason":"Requires `react-router-dom` v4 or v5 installed alongside v6 to provide the necessary legacy context and components for the compatibility layer.","package":"react-router-dom","optional":false}],"imports":[{"note":"This package re-exports the v5 `BrowserRouter` as `CompatRouter` to be used within a v6 application. You typically import it as an alias.","wrong":"import { CompatRouter } from 'react-router-dom-v5-compat'; // Incorrect alias","symbol":"CompatRouter","correct":"import { BrowserRouter as CompatRouter } from 'react-router-dom-v5-compat';"},{"note":"Re-exports the v5 `Switch` component, which is crucial for v5 route matching logic. `Switch` was removed in v6.","wrong":"import { CompatSwitch } from 'react-router-dom-v5-compat'; // Incorrect alias","symbol":"CompatSwitch","correct":"import { Switch as CompatSwitch } from 'react-router-dom-v5-compat';"},{"note":"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.","wrong":"import { useHistory } from 'react-router-dom-v5-compat'; // Ambiguous with v6's useNavigate","symbol":"useCompatHistory","correct":"import { useHistory as useCompatHistory } from 'react-router-dom-v5-compat';"}],"quickstart":{"code":"import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport { BrowserRouter as Router, Routes, Route, Link } from 'react-router-dom';\nimport { BrowserRouter as CompatRouter, Switch as CompatSwitch, useHistory as useCompatHistory } from 'react-router-dom-v5-compat';\n\n// A v5-style component\nfunction OldHomePage() {\n  const history = useCompatHistory();\n  const handleClick = () => {\n    history.push('/old-about');\n  };\n  return (\n    <div>\n      <h2>Old Home Page (v5 compat)</h2>\n      <button onClick={handleClick}>Go to Old About</button>\n      <Link to=\"/v6-dashboard\">Go to v6 Dashboard</Link>\n    </div>\n  );\n}\n\n// Another v5-style component\nfunction OldAboutPage() {\n  return <h2>Old About Page (v5 compat)</h2>;\n}\n\n// A v6-style component\nfunction V6Dashboard() {\n  return <h2>V6 Dashboard</h2>;\n}\n\nfunction App() {\n  return (\n    <Router>\n      <h1>Mixed React Router App</h1>\n      <Routes>\n        {/* v6 routes */}\n        <Route path=\"/v6-dashboard\" element={<V6Dashboard />} />\n        <Route path=\"/\" element={\n          <CompatRouter>\n            {/* v5 compatibility routes inside CompatRouter */}\n            <CompatSwitch>\n              <CompatRoute path=\"/old-about\" component={OldAboutPage} />\n              <CompatRoute path=\"/\" component={OldHomePage} />\n            </CompatSwitch>\n          </CompatRouter>\n        } />\n      </Routes>\n    </Router>\n  );\n}\n\nconst root = ReactDOM.createRoot(document.getElementById('root'));\nroot.render(<App />);","lang":"typescript","description":"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."},"warnings":[{"fix":"Prioritize refactoring v5-specific routing logic to use native `react-router-dom` v6 or v7 APIs (e.g., `useRoutes`, `useNavigate`, `Routes` component).","message":"This package is a temporary migration tool for React Router v6. It is not intended for long-term use and applications should aim for full migration to native React Router v6 (or later v7) constructs to leverage all performance and API benefits.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Always wrap v5-dependent components with `CompatRouter` and use the aliased `Compat` prefixed hooks and components from `react-router-dom-v5-compat` when working with v5 logic.","message":"Mixing `react-router-dom` v5 and v6 contexts and hooks directly can lead to unexpected behavior or runtime errors. Ensure that v5 compatibility components/hooks (e.g., `useCompatHistory`) are only used within a `CompatRouter` context.","severity":"gotcha","affected_versions":">=6.0.0"},{"fix":"Plan and execute a complete migration to `react-router-dom` v6 or v7 as soon as feasible. Consult the official React Router migration guides for detailed steps.","message":"The underlying `react-router-dom` v5 itself is considered deprecated, with `react-router` having moved to v7. While `v5-compat` helps with the v6 transition, new development should target the latest stable version of `react-router-dom`.","severity":"deprecated","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure that any component using `useCompatHistory` or similar compatibility hooks is a child of `CompatRouter` (or `BrowserRouter as CompatRouter`).","cause":"Attempting to use `useCompatHistory` or other `useCompat` hooks outside of a component rendered within a `CompatRouter` context.","error":"Error: Invalid hook call. Hooks can only be called inside of the body of a function component."},{"fix":"Verify 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.","cause":"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.","error":"Error: No routes matched location \"/path\""},{"fix":"Confirm that the component calling `useCompatHistory` is rendered within the component tree established by `CompatRouter`.","cause":"Likely attempting to access `history.push` from `useCompatHistory` before the history object is properly initialized by the `CompatRouter` or outside its scope.","error":"TypeError: Cannot read properties of undefined (reading 'push')"}],"ecosystem":"npm"}