Skip to main content

​
HashRouter

A declarative <Router> that stores the location in the hash portion of the URL (window.location.hash) so it is not sent to the server. This is useful for situations where you cannot configure your server to handle URLs properly, such as when deploying to static file hosts.

​
Import

import { HashRouter } from "react-router";

​
Type Declaration

interface HashRouterProps {
  basename?: string;
  children?: React.ReactNode;
  unstable_useTransitions?: boolean;
  window?: Window;
}

function HashRouter(props: HashRouterProps): React.ReactElement;

​
Props

​
basename
string
The base URL for all locations. If your app is served from a subdirectory, set this to the subdirectory path.
<HashRouter basename="/app">
  <Routes>
    <Route path="/" element={<Home />} /> {/* URL: /#/app/ */}
  </Routes>
</HashRouter>
​
children
React.ReactNode
Your route configuration, typically <Routes> and <Route> elements.
​
unstable_useTransitions
boolean
Control whether router state updates are wrapped in React.startTransition.
  • undefined (default): All state updates are wrapped in startTransition
  • true: Link/Form navigations and all state updates use startTransition
  • false: Router doesn’t use startTransition at all
See React Transitions for more details.
​
window
Window
Override the default window object. Useful for testing or iframe scenarios.

​
Examples

​
Basic Usage

import { HashRouter, Routes, Route } from "react-router";

function App() {
  return (
    <HashRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
      </Routes>
    </HashRouter>
  );
}
The URLs will be:
  • Home: http://example.com/#/
  • About: http://example.com/#/about

​
With Basename

<HashRouter basename="/app">
  <Routes>
    <Route path="/" element={<Home />} />
    <Route path="/settings" element={<Settings />} />
  </Routes>
</HashRouter>
The URLs will be:
  • Home: http://example.com/#/app/
  • Settings: http://example.com/#/app/settings

​
Custom Window (Testing)

import { HashRouter } from "react-router";
import { render } from "@testing-library/react";

test("renders with custom window", () => {
  const customWindow = { ...window, location: { hash: "#/test" } };
  
  render(
    <HashRouter window={customWindow}>
      <Routes>
        <Route path="/test" element={<div>Test Page</div>} />
      </Routes>
    </HashRouter>
  );
});

​
When to Use

Use HashRouter when:
  • You’re deploying to static file hosts (GitHub Pages, AWS S3, Netlify without rewrites)
  • You cannot configure your server to handle client-side routing
  • You need all routing to happen purely on the client
Hash-based routing has several limitations:
  • URLs look less clean with the # symbol
  • Server-side rendering is not possible
  • SEO is more difficult since the hash is not sent to the server
  • Some analytics tools don’t track hash changes properly
For modern deployments, prefer <BrowserRouter> with proper server configuration, or use createHashRouter() for the Data Router API.

​
Comparison with BrowserRouter

FeatureHashRouterBrowserRouter
URL Formatexample.com/#/pathexample.com/path
Server ConfigNot requiredRequired
SSR SupportNoYes
SEOLimitedFull
Clean URLsNoYes
Static Hosting✅ Works greatRequires rewrites

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us