React Router v7: Choosing Between createBrowserRouter and createHashRouter

When building a modern web application, especially with React Router v7, understanding the right type of router to use is crucial for ensuring smooth navigation, proper deep linking, and compatibility with your deployment environment. One of the most common confusions is whether createBrowserRouter can be used to create a hash-based router.

Let’s clear this up — and explore the deeper considerations around choosing the right router for your app.

🧠 The Core Difference: Browser vs. Hash Routers

React Router v7 offers two main router creation functions:

1. createBrowserRouter

• Uses the HTML5 History API
• Produces clean, user-friendly URLs like /dashboard, /settings
• Requires server-side configuration to support routing (e.g., fallback to index.html)

2. createHashRouter

• Uses the URL hash (#) for routing
• URLs look like /#/dashboard, /#/settings
• Does not require server configuration for deep linking
• Ideal for environments without server-side routing control, such as Chrome Extensions or GitHub Pages

👉 Important:
createBrowserRouter cannot be used to create a hash-based router. If you attempt to use it expecting hash behavior, your routes will break in environments where the server cannot handle client-side routing.

🛠️ Which Should You Use?

Here’s a simple rule of thumb:

⚠️ Real-world Considerations

🧩 Chrome Extension Development

• In Chrome Extensions, routing with the HTML5 History API (createBrowserRouter) can lead to broken links because you cannot configure the server to fallback to index.html.
• Use createHashRouter for guaranteed navigation compatibility.

🔀 Deployment Environments

• But if you’re deploying to platforms like GitHub Pages or IPFS, hash routing is the safest bet.

Platforms like Netlify and Vercel support rewrite rules to handle browser history routing. For example, in Netlify you can add a _redirects file:

/*    /index.html   200

📂 File System Access

• With createBrowserRouter, direct access to nested routes like /settings will fail if the server does not route all requests to index.html.
• With createHashRouter, everything after # is client-side only — no server-side config needed.

🧪 Example: How to Use createHashRouter

import { createHashRouter, RouterProvider } from "react-router-dom";
import App from "./App";
import About from "./About";

const router = createHashRouter([
  {
    path: "/",
    element: <App />,
    children: [
      { path: "about", element: <About /> },
    ],
  },
]);

function Root() {
  return <RouterProvider router={router} />;
}

This ensures that navigation works properly even if the user refreshes the page or pastes a deep link like /#/about.

🔮 Should You Ever Migrate from Hash to Browser Router?

Yes, if:

• You move from static hosting to a proper server (e.g., Node, Laravel, Nginx, etc.)
• You want SEO-friendly URLs (hash fragments are not indexed by search engines)
• You want to leverage analytics or structured URLs

Migration would involve:

• Switching to createBrowserRouter
• Setting up route rewrites or fallback rules on the server

📝 Finally

Choosing between createBrowserRouter and createHashRouter isn't about which is "better" — it's about what your deployment environment supports and what experience you want to give your users.

• Use createBrowserRouter if you control the backend and want clean URLs.
• Use createHashRouter if you're building a Chrome Extension, hosting on static sites, or want zero-config routing.

💡 Pro Tip: Don't forget to test routing behavior in your actual deployment environment, not just your local dev setup. Many routing issues only surface after deployment.

If you're building a Chrome Extension or targeting restricted hosting environments, stick to createHashRouter. Otherwise, go with createBrowserRouter for cleaner URLs and better SEO.

Support Us