Chapter 26: Path Params

Core Idea

Path params ($name) match a single URL segment up to the next / and expose it as a typed, named value in loader, beforeLoad, and components via Route.useParams(); TanStack Router also supports prefixes/suffixes, optional params, and custom parse/stringify/priority logic for advanced matching.

Key Concepts

• $paramName: Declares a dynamic segment; valid anywhere in a path ($postId, about/$name, team/$teamId). Matches only up to the next /, so child routes can continue the hierarchy.
• params in loader/beforeLoad: Both receive a params object keyed by param name with string values parsed from the URL (e.g. visiting /blog/123 on /posts/$postId gives { postId: '123' }).
• Route.useParams(): Typed hook to read params inside a route's own component.
• Global useParams({ strict: false }): Reads params from any component in the app, outside a specific route's context, at the cost of losing strict typing.
• params.parse / params.stringify / params.priority: Custom per-route param transformation. parse can return false to reject a candidate route (falling through to the next match, e.g. a numeric-only $postId route falling back to a $slug route); priority (default 0, higher tried first) controls ordering only among competing routes that use params.parse; static routes still always match before dynamic/optional/wildcard ones regardless of priority. parse must be deterministic/side-effect-free, it may run more than once during route planning.
• Prefix/Suffix Params (prefix{$param}suffix): Wrap the param name in {} and place literal text outside the braces, e.g. post-{$postId} or {$fileName}[.]txt (bracket-escaped dot). Combinable with splat routes too.
• Optional Params ({-$param}): See Ch 15/21; in this chapter covered in depth including navigation (params: {} inherits, params: { x: undefined } removes), loaders/beforeLoad receiving possibly-undefined values, and i18n locale-prefix routing patterns (/{-$locale}/about).
• pathParamsAllowedCharacters: Router option controlling which extra URI-valid characters (beyond default encodeURIComponent escaping) are allowed unescaped in params, e.g. ['@']. Allowed set: ; : @ & = + $ ,.

Code Examples

export const Route = createFileRoute('/posts/$postId')({
  params: {
    priority: 10,
    parse: ({ postId }) => {
      if (!/^\d+$/.test(postId)) return false
      return { postId: Number(postId) }
    },
    stringify: ({ postId }) => ({ postId: String(postId) }),
  },
})

• What it demonstrates: A numeric-only param parser with higher priority, falling through to a $slug-style fallback route when the raw param isn't numeric.

Key Takeaways

1. Params are always strings unless you provide a custom params.parse/stringify pair to coerce and reverse-coerce types (e.g. numbers).
2. params.priority only breaks ties between routes that both use params.parse; it never overrides the base specificity order (static > dynamic > splat) from Ch 17.
3. Prefix/suffix param syntax ({$param} with surrounding literal text) and optional params ({-$param}) both extend beyond simple $param segments to express more precise URL patterns without extra route nesting.
4. Use pathParamsAllowedCharacters sparingly and deliberately, changing default escaping can affect matching/security of adjacent segments.

Connects To

• Ch 15 / Ch 21: Routing Concepts and File Naming Conventions, define the $ token and {-$param} optional syntax used throughout this chapter.
• Ch 17: Route Matching, explains the base specificity order that params.priority operates within.
• Ch 23: Navigation, shows how params is passed to Link/navigate.
• Ch 33: Internationalization, builds on the {-$locale} prefix pattern shown here.