Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 50 ยท Declarative Routing Basics

Routes and Matching

Learn how React Router matches URLs to routes: path patterns, params, splats, specificity ranking, index routes, trailing slashes and case sensitivity.

A route is a promise: "when the URL looks like this, show that." The router's job is to find the best promise to keep for the URL in front of it. Most of the time that is obvious, but as soon as an app has /users/new next to /users/:id, or a catch-all route for unknown pages, you need to know exactly how the router decides. In older routers (React Router 5 and earlier) the order of your routes decided, and putting them in the wrong order was a classic source of bugs. In React Router 6 and 7 the router ranks the routes by how specific they are, so order no longer matters.

This lesson covers the path patterns you can write, how ranking picks a winner, what an index route is, and how trailing slashes and upper-case letters are treated. The real library code is read-only, and two runnable stand-ins let you experiment with first-match-wins versus ranking.

Path patterns

A path is a string of segments separated by slashes. Each segment is one of three things:

Segment Example Matches
Static products Exactly that text (ignoring upper and lower case by default).
Dynamic (param) :id Any single non-empty segment; the value is available through useParams().
Splat * Everything that is left, including slashes. Only allowed as the last segment.
JSX
// Real React Router patterns (read-only)
<Routes>
  <Route path="/" element={<Home />} />                    {/* exactly / */}
  <Route path="/products" element={<ProductList />} />     {/* exactly /products */}
  <Route path="/products/:id" element={<Product />} />     {/* /products/7, params.id is "7" */}
  <Route path="/products/:id/edit" element={<Edit />} />   {/* two params are fine: /orders/:orderId/items/:itemId */}
  <Route path="/files/*" element={<FileBrowser />} />      {/* /files/a/b/c, params["*"] is "a/b/c" */}
  <Route path="/:lang?/about" element={<About />} />       {/* optional segment: /about and /fr/about */}
  <Route path="*" element={<NotFound />} />                {/* anything nothing else matched */}
</Routes>

Three limits are worth knowing, because people try to break them every week:

  • A dynamic segment is a whole segment. /user-:id or /:year-:month do not work. Match /:slug and split it yourself.
  • There are no regular expressions in paths. If you need to check that :id is a number, validate it in the component or loader and show a not-found page otherwise.
  • A splat is last. The * captures the rest, and useParams() returns it under the key "*".

Routes are matched against the pathname only. The query string (?sort=price) and the hash (#top) are ignored, as explained in How Routing Works Under the Hood.

Ranking: why order does not matter

Suppose you have these three routes and the URL is /users/new:

  • /users/:id
  • /users/new
  • *

All three match. A router that simply used the first match in the list would show the user profile with id = "new", which is wrong. React Router instead gives every route a score and picks the highest one that matches:

flowchart LR
  A["All route patterns<br/>(flattened, nested too)"] --> B["Score each one<br/>static > dynamic > splat"]
  B --> C["Sort by score,<br/>highest first"]
  C --> D["First that matches<br/>the URL wins"]

The router scores every pattern once, sorts them, and only then compares them to the URL.

The exact numbers are an implementation detail that can change, but the rules are stable:

  • A static segment counts for much more than a dynamic one, so /users/new beats /users/:id.
  • A splat is penalized, so * loses to everything else and only wins when nothing else matches.
  • More segments score higher than fewer, so /users/:id/edit is tried before /users/:id.
  • An index route gets a small bonus over its sibling layout, so the index wins for the parent's exact path.

The result is that you can write routes in any order and the most specific one wins. The stand-in below lets you see the difference. Its default mode is deliberately the old one: first match wins, and the routes are in a bad order. Click "/users/new", then switch to "ranked".

First match wins versus ranked matching

With the checkbox off, /users/new is swallowed by /users/:id and the params show {"id":"new"}. With ranking on, the static route /users/new is tried first. The scores here follow the same idea as the real library (static high, dynamic lower, splat negative) but are not its exact numbers.

Because ranking looks at the whole pattern, you can still organize routes however reads best. Put the routes that belong together next to each other and let the router sort it out.

Index routes

When you nest routes (the full story is in Nested Routes and Outlet), a parent such as /dashboard renders a layout, and its children fill a slot inside it. But what should appear inside the slot when the URL is exactly /dashboard, with no child segment? That is the job of an index route: a child written with the index prop and no path. It renders when the parent's path matches and nothing is left over.

JSX
// Real React Router (read-only)
<Route path="/dashboard" element={<DashboardLayout />}>
  <Route index element={<Overview />} />              {/* /dashboard */}
  <Route path="settings" element={<Settings />} />    {/* /dashboard/settings */}
</Route>

An index route cannot have children, and a parent without one simply leaves its slot empty at the parent's exact URL. Child paths such as settings are written relative to the parent; no leading slash.

Trailing slashes and case

Two small rules prevent a lot of 404 reports:

  • Trailing slashes are ignored when matching. /about and /about/ both match path="/about". The router does not redirect between them, so if you care which form search engines see, decide it at the server or CDN.
  • Matching is case-insensitive by default. /About matches path="/about". Add caseSensitive on a Route to turn that off for that route. Params keep the case the user typed.
Probing trailing slashes, case and index routes

Tick the checkbox: /About and /ABOUT/ stop matching, while the trailing slash stays harmless. In the second table, /dashboard shows the index child inside the layout, while /dashboard/reports matches no child at all, so nothing in the layout's slot would render. A catch-all route inside the parent is how you give that case a proper "not found" screen.

Common matching mistakes

  • Leading slashes on child paths. In nested routes write path="settings", not path="/settings". An absolute child path must still start with its parent's path.
  • Expecting regular expressions. There are none. Validate params in code.
  • Forgetting that params are strings. /products/7 gives "7", never the number 7. See Dynamic Segments and useParams.
  • Relying on route order when porting version 5 code. In version 6 and 7 it does not matter, so you can delete the workarounds.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. The URL is /users/new and your routes are /users/:id and /users/new. Which one does React Router 7 render?

    React Router ranks routes by specificity, not by order. Static segments score more than dynamic ones, so /users/new wins regardless of where it is declared.
  2. 2. Which pattern is NOT supported?

    A dynamic segment must be a whole segment. Mixing static text and a param in one segment (user-:id) does not work, so match :slug and parse it yourself.
  3. 3. What is an index route?

    An index route fills the parent's outlet when the URL is exactly the parent's path. It cannot have children.
  4. 4. By default, does path="/about" match the URL /About/?

    Matching ignores case and a trailing slash unless you add the caseSensitive prop on the route.

Summary

  • Path segments are static (products), dynamic (:id) or a splat (*, last only); there are no regular expressions and dynamic segments cannot share a segment with text.
  • Routes are matched against the pathname only, and the router ranks them by specificity, so declaration order no longer matters.
  • Static segments beat dynamic ones, and a splat loses to everything, which makes * a safe fallback.
  • An index route (index, no path) renders when the parent's path matches exactly, and it cannot have children.
  • Matching ignores trailing slashes and, unless caseSensitive is set, upper and lower case.

Next: Link and NavLink