Router FAQ
Purpose and Scope
This FAQ answers recurring questions that come up when adopting TanStack Router and deciding which Router APIs to reach for. The Router documentation positions the route tree as the application contract: route files, URLs, params, search schemas, loader data, context, links, and navigation should all agree. The repository API index supports that framing by grouping public Router surface area into functions, components, hooks, and types instead of a single monolithic entry point. Use this page when you know the problem you are solving but are unsure which guide or API family owns it.
Sources: docs/router/api/router.md
Relevant Source Files
docs/router/api/router.md- The Router API index that lists the public functions, components, hooks, and types used to answer these FAQ entries and route readers to the right reference areas.
Common Adoption Questions
Is TanStack Router only a path matcher?
No. Treat Router as a typed application contract rather than only a URL-to-component matcher. The public API index includes route creation functions such as createRoute, createFileRoute, createRootRoute, and createRootRouteWithContext, which are the foundation for declaring the tree that later drives links, navigation, params, search, loaders, and route context. If you are comparing Router to simpler routing libraries, the key difference is that route definitions are intended to become typed APIs throughout the app, not just a runtime registry of path strings.
Sources: docs/router/api/router.md
Should I start with code-based routes or file-based routes?
Both models are represented in the API. Code-based routing centers on functions like createRoute, createRootRoute, and createRouter; file-based routing centers on createFileRoute, createLazyFileRoute, and the generated route tree used by the build tooling. A small app or migration may be easiest to understand with explicit route objects, while a larger product often benefits from file conventions and generated types. If your question involves generated route maps, route files, or automatic code splitting, continue to the file-based routing and route-generation pages rather than staying in the base API index.
Sources: docs/router/api/router.md
Where do navigation and links get their type safety?
Navigation is split across declarative components, imperative hooks, reusable option helpers, and types. <Link> and <Navigate> cover common component-level navigation, while useNavigate, useMatchRoute, useLocation, and useRouterState support component logic that reacts to or initiates routing. The API index also includes linkOptions, LinkOptions, NavigateOptions, ToOptions, ActiveLinkOptions, and MatchRouteOptions, which shows that link and navigation configuration is itself a first-class typed contract. When a navigation call does not autocomplete as expected, inspect the route tree and the corresponding link or navigation option type together.
Sources: docs/router/api/router.md
How should I think about search params?
Router treats search params as typed URL state, not as an unstructured string appended to the path. The FAQ-level signal in the API index is the presence of useSearch for reading search state, retainSearchParams and stripSearchParams for controlling how search data carries across navigation, and typed navigation options that include destination and search configuration. If you are validating filters, pagination, dates, arrays, or object-like query values, read the search-params and custom-search-param-serialization guides next. The important habit is to define search behavior at the route boundary and consume it through Router APIs rather than parsing window.location.search ad hoc.
Sources: docs/router/api/router.md
Runtime Behavior Questions
Where do loader data and deferred data show up in components?
Loader data belongs to route matches and is consumed through hooks and components that understand the current match. The API index lists useLoaderData and useLoaderDeps for reading loaded values and loader dependencies, and it also lists defer, <Await>, and useAwaited for deferred or asynchronous data flows. That grouping is a useful clue for troubleshooting: if the question is about when data is fetched, cached, invalidated, or marked pending, start with data-loading; if the question is about rendering a promise-like value after navigation has already begun, start with deferred data loading.
Sources: docs/router/api/router.md
How do I handle redirects, not-found states, and errors?
Router separates navigation-oriented redirects from route errors and not-found handling. The functions redirect, notFound, isRedirect, and isNotFound are listed alongside components such as <CatchBoundary>, <CatchNotFound>, <DefaultGlobalNotFound>, <ErrorComponent>, and <NotFoundComponent>. This means an app can throw or return route-level control flow, detect that control flow when needed, and render appropriate boundaries in the tree. If a redirect or not-found result appears to bypass the component you expected, follow the route hierarchy and check which boundary or not-found component is closest to the match that produced it.
Sources: docs/router/api/router.md
What is the difference between router context, route context, and ordinary props?
Context is part of the route contract, while props are local component inputs. The API index points to createRootRouteWithContext for establishing typed root context and to useRouteContext, useMatch, useMatches, useParentMatches, and useChildMatches for reading information from matched routes. Use context for dependencies that loaders, guards, and routes need consistently, such as authentication state or clients. Use ordinary component props for reusable UI that does not need to participate in matching, navigation, or data loading. If context types disappear, verify root route registration and the Register type relationship.
Sources: docs/router/api/router.md
API Lookup Cheat Sheet
| Question | Start with | Why |
|---|---|---|
| How do I create routes? | createRoute, createFileRoute, createRootRoute, createRouter | These functions define the route tree and router instance. |
| How do I navigate? | <Link>, <Navigate>, useNavigate, linkOptions | These APIs connect typed destinations to UI and imperative actions. |
| How do I read route state? | useLocation, useRouterState, useMatch, useMatches | These hooks expose the current location and matched route information. |
| How do I read params or search? | useParams, useSearch | These hooks consume typed URL state from the active route context. |
| How do I handle data? | useLoaderData, useLoaderDeps, defer, <Await> | These APIs connect route loaders, dependencies, and deferred rendering. |
| How do I handle failures? | redirect, notFound, <CatchBoundary>, <CatchNotFound> | These functions and components model routing control flow and display boundaries. |
The API index is intentionally broad, so it is best used as a map rather than a tutorial. If the issue is conceptual, start with the corresponding guide: routing concepts for tree structure, navigation-and-links for links, data-loading for loaders, search-params for URL state, and not-found-errors-and-error-boundaries for failures. If the issue is a TypeScript or call-signature question, use the reference page named by the API entry. This workflow keeps the docs path short: guide first for mental model, reference second for exact options and exported names.
Sources: docs/router/api/router.md
Troubleshooting Direction
When Router behavior surprises you, reduce the problem to one of four contracts: route definition, navigation target, URL state, or rendered match. Route definition problems usually involve createRoute, createFileRoute, root route creation, or lazy route APIs. Navigation target problems usually involve <Link>, <Navigate>, useNavigate, or shared LinkOptions. URL-state problems usually involve params, search, history state, or ParsedLocation. Rendered-match problems usually involve <Outlet>, match hooks, loader hooks, or error and not-found boundaries. Naming the contract first makes the API index much easier to use.
Sources: docs/router/api/router.md
For production architecture questions, decide whether the app is still a Router-only client application or whether it needs TanStack Start. Router owns the typed route tree, loaders, URL state, matching, navigation, and rendering boundaries described by this API index. Start builds on Router when the same route tree needs full-stack capabilities such as server rendering, streaming, and server functions. If your FAQ is really about deployment targets, server execution, or full-document rendering, move from Router troubleshooting to the Start overview and deployment pages after confirming the Router route contract works locally.
Sources: docs/router/api/router.md