HashRouter: routing without server configuration

WHY IT EXISTS: In a traditional multi-page website, the server maps each URL path to a specific HTML file. Single-page applications ship one JavaScript bundle, so the client must fake navigation by swapping components in place. The problem is that if a user refreshes the page or shares a deep link, the server receives the full path and often returns a 404 because no physical file exists at routes like /dashboard or /settings. HashRouter exists to eliminate that server dependency entirely by keeping the route information in a place the server never looks.

THE MENTAL MODEL: Imagine a scroll-to-anchor link inside a long document. The browser jumps to the section after the hash symbol without asking the server for a new page. HashRouter hijacks that same mechanism for application routing. The server thinks every request is for the root page, while the React app treats the fragment as its own private address bar. It is a client-side only trick that trades URL aesthetics for guaranteed delivery on any host.

HOW IT WORKS: HashRouter sets up a listener for the hashchange event on the window object. When someone clicks a Link component, React Router updates window.location.hash instead of pushing a new history entry with the full path. On initial load, the router reads the current hash, strips the leading symbol, and matches the remaining string against your route table. Because the fragment identifier is never transmitted in an HTTP request, the server happily serves index.html and the app bootstraps itself from the hash value on every single visit.

WHEN TO USE IT: Reach for HashRouter when you deploy to static hosting that offers no server-side configuration, such as GitHub Pages, Netlify without a redirects file, or an S3 bucket serving raw files. It is also common in Electron apps and embedded browser views where there is no web server at all, just a local file opening in a WebView that still needs navigation state.

WHEN NOT TO USE IT: Avoid HashRouter for public marketing sites, blogs, or e-commerce storefronts. Search engines may not index content behind a hash fragment, social previews often drop the fragment, and analytics platforms sometimes fail to record hash changes as distinct pageviews without manual instrumentation. If you control the server or CDN and can configure a simple catch-all rewrite to index.html, use BrowserRouter instead.

ONE CANONICAL EXAMPLE: You build a React dashboard and host it on GitHub Pages. You start with BrowserRouter and everything works locally, but a visitor refreshes the page at /reports and GitHub serves a 404 because it searches for a reports.html that does not exist. You switch to HashRouter, and the URL becomes /#/reports. Now GitHub always serves the root index.html, and your app reads the hash on startup to render the Reports component. The dashboard survives refreshes and direct links, but you accept that the URL will never look clean and some SEO value is lost.