tanstack-router-route-trees-and-navigation

TanStack Router Route Trees and Navigation

Use this skill when the task is primarily about route structure, route matching, or user navigation semantics.

Scope

• route-tree mental model across code-based and file-based routing
• nested routes, layout routes, pathless routes, and index routes
• dynamic params and splat segments
• Link, Navigate, useNavigate, and router.navigate
• route masking and typed navigation state

Routing cues

• route trees, getParentRoute, addChildren, nesting, params, Link, Navigate, useNavigate, route matching, or route masking -> use this skill
• install choices, bundler setup, quick start, or file-based vs code-based selection -> use tanstack-router-overview-and-setup
• validateSearch, loaderDeps, loader, beforeLoad, auth guards, route context, or preloading -> use tanstack-router-search-params-and-loaders
• pendingComponent, errorComponent, notFoundComponent, scroll restoration, navigation blocking, or head management -> use tanstack-router-runtime-behavior-and-ssr
• routeTree.gen.ts, file naming conventions, virtual routes, .lazy.tsx, plugin config, or CLI generation -> use tanstack-router-file-based-routing-and-tooling

Workflow

1. Read references/route-tree-mental-model.md first.
2. If the task touches relative navigation, masking, or shared link helpers, read references/navigation-and-masking.md.
3. Keep the route tree and navigation helpers aligned with the registered router type.
4. Narrow shared navigation with from or to when route breadth or TypeScript cost starts to grow.

Quick example

import {
  Link,
  Outlet,
  createRootRoute,
  createRoute,
  createRouter,
} from '@tanstack/react-router'

const rootRoute = createRootRoute({
  component: () => (
    <>
      <nav>
        <Link to="/posts">Posts</Link>
      </nav>
      <Outlet />
    </>
  ),
})

const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'posts',
  component: () => <div>Posts</div>,
})

const routeTree = rootRoute.addChildren([postsRoute])
export const router = createRouter({ routeTree })

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

Guardrails

• Keep one clear parent chain. In code-based routing, every non-root route needs getParentRoute.
• Pathless routes use id, not path. They can group UI and context, but the URL segment must live on a real path route.
• Index routes represent the exact parent URL. They are not a second path segment.
• Use Link for normal in-app navigation. Reserve useNavigate, router.navigate, or Navigate for imperative or redirect-like flows.
• Pass params and search intentionally. Prefer updater functions when preserving parts of the current location.
• Treat route masking as navigation behavior. The visible URL can differ from the underlying route match, so keep masks close to the links or helpers that own that experience.

Canonical APIs

• createRootRoute
• createRoute
• createFileRoute
• createRouter
• Link
• Navigate
• useNavigate
• createRouteMask

Maintenance

• Snapshot date: 2026-03-24
• Package snapshot: @tanstack/react-router@1.168.3

References

• references/route-tree-mental-model.md
• references/navigation-and-masking.md