Router API Overview
Purpose and Scope
The Router API reference is the map for moving from concepts and guides into exact public entry points. It is organized around the way an application author uses TanStack Router: first defining routes and a router, then rendering route UI, then reading router state through hooks, and finally relying on shared types for strongly typed navigation, route matching, history, and errors. This overview does not replace the per-symbol pages. Instead, it explains how the reference is grouped so you can choose the right page when you are implementing a route tree, composing navigation components, debugging state, or checking TypeScript contracts.
Sources: docs/router/api/router.md
The index is intentionally broad: it lists functions, components, hooks, and types in one top-level Router API page. That means the reference is not only a React component catalog and not only a core router class reference. It spans route creation helpers such as createRoute, file-route helpers such as createFileRoute, navigation helpers such as redirect, render components such as <Outlet> and <Link>, state hooks such as useRouterState, and structural types such as RouterOptions, RouterState, RouteMatch, and ParsedLocation. Treat this page as the table of contents for the public API surface.
Sources: docs/router/api/router.md
Relevant Source Files
docs/router/api/router.md- Defines the Router API reference index and groups linked API pages under Functions, Components, Hooks, and Types.
API Categories at a Glance
The Functions section is where most route-tree and imperative helper APIs begin. Route construction is represented by createRootRoute, createRootRouteWithContext, createRoute, createFileRoute, createLazyFileRoute, createLazyRoute, and createRouter. Runtime utilities and route behaviors are also listed here, including defer for deferred data workflows, getRouteApi for route-scoped API access, lazyRouteComponent for lazy component loading, linkOptions for reusable navigation options, createRouteMask for masked navigation, and the error/navigation helpers notFound, redirect, isNotFound, and isRedirect. Search-param utilities retainSearchParams and stripSearchParams complete the function group.
Sources: docs/router/api/router.md
The Components section is the reference path for APIs that render UI or participate directly in route rendering. Use <Outlet> when you need to understand nested child rendering, <Link> for declarative navigation, <Navigate> for render-driven redirects or navigation, and <MatchRoute> when UI should depend on whether a route matches. Error and not-found rendering are represented by <CatchBoundary>, <CatchNotFound>, <ErrorComponent>, <NotFoundComponent>, and <DefaultGlobalNotFound>. Deferred or environment-specific rendering is covered by <Await> and <ClientOnly>, which sit next to routing components because they affect what the user sees during loading or client-only execution.
Sources: docs/router/api/router.md
The Hooks section is the reference path for reading router state from framework components and for issuing navigation from component code. useRouter gives access to the router instance, while useRouterState, useLocation, useMatches, useMatch, useParentMatches, and useChildMatches expose progressively more specific match and location information. Route data and route-scoped values are covered by useLoaderData, useLoaderDeps, useParams, useSearch, and useRouteContext. Navigation and link composition are represented by useNavigate, useLinkProps, useMatchRoute, useCanGoBack, and useBlocker; deferred data consumption is represented by useAwaited.
Sources: docs/router/api/router.md
System-to-Code Mapping
| Reader task | Start with | Why this category matters |
|---|---|---|
| Define route trees | createRootRoute, createRoute, createFileRoute, createRouter | These functions establish the route definitions and router instance that the rest of the app uses. |
| Render route UI | <Outlet>, <Link>, <Navigate>, <CatchBoundary> | Components connect the route tree to visible layouts, navigation, redirects, and error states. |
| Read state in components | useLocation, useParams, useSearch, useLoaderData, useRouterState | Hooks expose typed location, match, loader, search, and router state to framework code. |
| Share navigation contracts | LinkOptions, NavigateOptions, ActiveLinkOptions, ToOptions | Types describe reusable navigation objects and active-link behavior. |
| Handle redirects and not-found flows | redirect, notFound, isRedirect, isNotFound, Redirect, NotFoundError | Helpers and types make exceptional routing outcomes explicit and testable. |
Type Reference Map
The Types section should be read as the stable vocabulary behind the functions, components, and hooks. Navigation-oriented types include ActiveLinkOptions, LinkOptions, LinkProps, NavigateOptions, MatchRouteOptions, ToOptions, ToMaskOptions, and UseMatchRouteOptions. Router structure and state are represented by Router, RouterOptions, RouterState, RouterEvents, Route, RouteOptions, RouteApi, RouteMask, RouteMatch, and Register. History and location are represented by HistoryState, ParsedHistoryState, and ParsedLocation, while error/navigation outcomes include Redirect and NotFoundError. When TypeScript reports an incompatibility, these type pages are usually the shortest path from an error message to the intended public contract.
Sources: docs/router/api/router.md
A practical way to use the type pages is to start from the API you are calling, then follow the option type it accepts. For example, when a link abstraction is hard to type, begin with linkOptions, <Link>, or useLinkProps, then compare the related LinkOptions, LinkProps, and ActiveLinkOptions pages. When router creation is the issue, start with createRouter and continue to RouterOptions, RouterState, and RouterEvents. When route matching or route-specific data is the issue, read the hook page first, then check RouteMatch, RouteApi, RouteOptions, and the relevant params, search, or loader concepts in the guides.
Sources: docs/router/api/router.md
How to Navigate the Reference
Use the reference in task order rather than alphabetically. If you are creating routes, begin in Functions and only move into Types when an option object or inferred generic needs clarification. If you are composing UI, begin in Components, because the rendered APIs describe the behavior developers see at call sites. If you already have a route tree and need data inside a component, start in Hooks. If you are designing shared abstractions for links, masks, route APIs, or router configuration, use the Types section early so your helper functions preserve the same public contracts as the Router APIs.
Sources: docs/router/api/router.md
This overview also helps separate API reference from conceptual learning. The reference tells you what public symbol exists and where its dedicated page lives; the guides explain when to choose one pattern over another. For example, createFileRoute and createRoute are both route-definition functions, but the choice between file-based and code-based routing belongs in the routing and file-based routing guides. Similarly, defer, <Await>, and useAwaited are API entries, while deferred loading strategy belongs in the data-loading guide. Read the reference when you need exact names and contracts; read the guides when you need architecture and sequencing.
Sources: docs/router/api/router.md
Next Steps
For route definition work, continue to the Routes API Reference and File Route API Reference. For UI and navigation work, continue to the Link and Navigation API Reference and Router Hooks API Reference. For router instance configuration, event handling, and state inspection, continue to Router Options, State, and Events. For thrown routing outcomes and search-param utility helpers, continue to Errors, Redirects, and Search Utilities. If you are still choosing an application model, read Routing Concepts and File-Based Routing before diving into the individual API pages.