Chapter 17: Route Matching

Core Idea

Regardless of the order routes are defined in the tree, TanStack Router automatically sorts them by specificity before matching, following a fixed precedence: index route, then static routes (most to least specific), then dynamic routes (longest to shortest), then splat/wildcard routes.

Key Concepts

• Automatic Sorting: The router pre-sorts the entire route tree by specificity at build/setup time, independent of source declaration order.
• Precedence Order: 1) Index route, 2) Static routes (most specific first, e.g. about/us before about), 3) Dynamic routes (longest path first, e.g. more segments before fewer), 4) Splat/wildcard routes (matched last, as the catch-all fallback).
• Matching Walk: For a given URL, the router walks the sorted tree top-down within each nesting level, testing each candidate until one succeeds; unmatched candidates are skipped (marked ❌ in the docs' visual walkthrough) until a match (✅) or the splat fallback is found.

Key Takeaways

1. Declaration order in your files/route tree does not affect matching; specificity always wins, so about/us will always be tried before the more generic about.
2. Static routes always outrank dynamic routes at the same level, and dynamic routes always outrank splat/wildcard routes, this is what lets you safely combine /blog/new, /blog/$postId, and a catch-all without conflicts.
3. A splat (* / $) route acts as the last-resort fallback within its subtree, useful for custom 404s scoped to a section of the app.

Connects To

• Ch 15: Routing Concepts, defines index/dynamic/splat route types whose matching order this chapter explains.
• Ch 16: Route Trees, the structure that gets sorted and matched.