Route Matching

Route matching follows a consistent and predictable pattern. This guide will explain how route trees are matched.

When TanStack Router processes your route tree, all of your routes are automatically sorted to match the most specific routes first. This means that regardless of the order your route tree is defined, routes will always be sorted in this order:

  • Index Route
  • Static Routes (most specific to least specific)
  • Dynamic Routes (longest to shortest)
  • Splat/Wildcard Routes

Consider the following pseudo route tree:

bash
Root
- blog
- $postId
- /
- new
- /
- *
- about
- about/us

After sorting, this route tree will become:

bash
Root
- /
- about/us
- about
- blog
- /
- new
- $postId
- *

This final order represents the order in which routes will be matched based on specificity.

Using that route tree, let's follow the matching process for a few different URLs:

  • /blog
    bash
    Root
    ❌ /
    ❌ about/us
    ❌ about
    ⏩ blog
    ✅ /
    - new
    - $postId
    - *
  • /blog/my-post
    bash
    Root
    ❌ /
    ❌ about/us
    ❌ about
    ⏩ blog
    ❌ /
    ❌ new
    $postId
    - *
  • /
    bash
    Root
    ✅ /
    - about/us
    - about
    - blog
    - /
    - new
    - $postId
    - *
  • /not-a-route
    bash
    Root
    ❌ /
    ❌ about/us
    ❌ about
    ❌ blog
    - /
    - new
    - $postId
    ✅ *

Pathless Route Matching

During matching, pathless routes are treated as if they are flat. If a route is not found in a pathless route's children, matching will continue out of the pathless route's children and on through the rest of the parent subtree like normal.

NotFoundRoutes and Matching

If you choose to configure a NotFoundRoute for your router, it should be passed to the notFoundRoute option and not as part of your routeTree. This is because NotFoundRoutes are not considered during matching and only render as a fallback when no other suitable match is found.

You can read more about NotFoundRoutes in the Not Found Errors guide.

Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.

scarf analytics