📄 tanstack/router/latest/docs/framework/react/routing/route-matching

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:

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


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

After sorting, this route tree will become:

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


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

Root
  ❌ /
  ❌ about/us
  ❌ about
  ⏩ blog
    ✅ /
    - new
    - $postId
  - *


Root
  ❌ /
  ❌ about/us
  ❌ about
  ⏩ blog
    ✅ /
    - new
    - $postId
  - *

/blog/my-post

Root
  ❌ /
  ❌ about/us
  ❌ about
  ⏩ blog
    ❌ /
    ❌ new
    ✅ $postId
  - *


Root
  ❌ /
  ❌ about/us
  ❌ about
  ⏩ blog
    ❌ /
    ❌ new
    ✅ $postId
  - *

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


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

/not-a-route

Root
  ❌ /
  ❌ about/us
  ❌ about
  ❌ blog
    - /
    - new
    - $postId
  ✅ *


Root
  ❌ /
  ❌ about/us
  ❌ about
  ❌ blog
    - /
    - new
    - $postId
  ✅ *

Edit on GitHub

Route Trees

File-Based Routing

Partners Become a Partner

scarf analytics