Router Options, State, and Events
Purpose and Scope
This page orients you to the Router instance as the operational center of a TanStack Router application. In TanStack Router, the route tree is the application contract: navigation, params, search state, loaders, route context, pending states, redirects, and errors all become APIs that are typed against that tree. The Router instance is where that contract becomes runtime behavior. You create it, provide it to the framework integration, observe its state through hooks, and use its associated types when writing application-level configuration or tooling.
Sources: docs/router/api/router.md
The official API index groups Router-related concerns into four practical categories: functions, components, hooks, and types. For this page, the important entries are createRouter, useRouter, useRouterState, Router Type, RouterOptions Type, RouterState Type, and RouterEvents Type. Those names form the public reference spine for configuring a router instance and observing what it is doing. The same index also places navigation, matching, redirects, not-found handling, search utilities, route definitions, and UI components nearby, which is a useful reminder that Router state is not isolated from the rest of the API surface.
Relevant Source Files
docs/router/api/router.md— The Router API hub that lists public functions, components, hooks, and types, includingcreateRouter,useRouter,useRouterState,Router Type,RouterOptions Type,RouterState Type, andRouterEvents Type.
API Surface Map
The Router API index presents createRouter as the public function for constructing a router, while the Router Type and RouterOptions Type entries describe the shape of the instance and its configuration. In application code, that usually means the route tree and router-level configuration are assembled before rendering framework components. Once the instance exists, other public APIs can rely on its typed route map: links can validate destinations, navigation calls can constrain params and search, loaders can participate in state transitions, and route errors can be represented consistently.
Sources: docs/router/api/router.md
| Category | Public API names shown in the index | Role in router instance work |
|---|---|---|
| Construction | createRouter | Creates the configured router instance from options such as the route tree and related router configuration. |
| Instance typing | Router Type | Describes the public Router instance type used by application code and integrations. |
| Configuration typing | RouterOptions Type | Describes the options object accepted when creating or configuring a router. |
| Runtime state typing | RouterState Type | Describes the state shape exposed for observation and selection. |
| Event typing | RouterEvents Type | Describes the event API surface used when observing router lifecycle and navigation activity. |
| Hooks | useRouter, useRouterState | Framework-facing access points for reading the router instance and selecting state from it. |
The same API hub lists related functions such as createRoute, createFileRoute, createRootRoute, createRootRouteWithContext, and getRouteApi. These are not router-state APIs themselves, but they define or consume the route contract that the router instance manages. For example, a root route with context affects what route code can read, a file route participates in the generated route tree, and route APIs let code reach typed helpers without passing untyped strings around. Router options and state should therefore be read as part of the broader route-tree system rather than as a standalone configuration object.
Configuration Model
RouterOptions Type is the reference entry for configuration. The supplied API index does not enumerate each option field, but it establishes that options are part of the public type surface rather than an internal implementation detail. That distinction matters for application authors and library authors. Application code can type configuration consistently, while integrations and examples can point users to a stable named type instead of relying on inferred object literals. The primary workflow is to define routes, create the router from those definitions and options, and then render against that configured instance.
Sources: docs/router/api/router.md
Because TanStack Router is route-tree driven, router options should be understood as the place where app-wide routing behavior is assembled around the route tree. The official product framing emphasizes that the generated route map keeps route files, params, search schemas, and loader outputs connected to the APIs used every day. At the Router instance level, that means configuration is not just about URL matching. It also supports a typed experience for navigation, URL state, loading, pending behavior, error boundaries, and code splitting through the public APIs listed alongside the Router references.
A useful mental model is to treat the Router instance as the boundary between definition-time and runtime. Definition-time APIs such as createRoute, createFileRoute, and createRootRouteWithContext describe what routes exist and what they can do. Runtime APIs such as Link, Navigate, useNavigate, useLocation, useMatches, useParams, useSearch, useLoaderData, and useRouteContext consume the configured router. The options object is what connects these layers into one application router rather than a collection of disconnected route declarations.
State and Observation
RouterState Type and useRouterState are the key source-backed names for reading router state. The API index lists useRouterState with the Router hooks, next to hooks for location, matches, params, search, loader data, route context, navigation, and blockers. That placement shows the intended observation model: use specialized hooks when you want a specific part of routing behavior, and use router-state access when you need a broader or selected view of the router’s current runtime state.
Sources: docs/router/api/router.md
For component code, this distinction keeps routing concerns focused. A component that only needs the current location should prefer useLocation; a component that needs matched routes can use useMatches; route modules can reach loader data through useLoaderData; navigation UI can use useNavigate, useCanGoBack, or link-related APIs. useRouterState is the more general entry point for state observation. It is appropriate when the caller is building cross-cutting UI, instrumentation, loading indicators, custom devtools-like panels, or framework integration points that need to understand the router beyond one route’s local data.
useRouter complements useRouterState by exposing the router instance itself rather than just selected state. That matters when code needs the configured object as an object with behavior, not merely a snapshot. The API index lists both hooks, which makes the division explicit: one hook is for the router object, and the other is for state. A clear codebase usually keeps those usages separate. Read state through state hooks, navigate through navigation APIs, and reach for the instance only when the task genuinely requires the router object.
Events and Lifecycle Signals
RouterEvents Type is the source-backed entry point for event typing. The index does not include the individual event names in the supplied evidence, so this page should be used as an orientation layer rather than a field-by-field event catalog. The important point is that events are exposed as a named public type alongside Router Type, RouterOptions Type, and RouterState Type. That placement signals that observing router lifecycle or navigation activity is part of the supported API surface, not only an internal concern.
Sources: docs/router/api/router.md
Event types are most useful when you are writing infrastructure around the router: analytics, debugging tools, telemetry, custom integrations, or application shells that need to respond to router activity. For ordinary route components, hooks like useLocation, useMatches, useSearch, and useLoaderData are usually a better fit because they keep data flow declarative. For cross-cutting observers, event typing gives TypeScript-aware code a stable contract for what the router can report. Use the RouterEvents Type reference when you need exact event payloads and the state reference when you need the corresponding runtime state shape.
The API index also lists error and redirect utilities near the Router types: redirect, notFound, isRedirect, and isNotFound, plus route error and redirect types. Those utilities often participate in lifecycle behavior because navigation may resolve successfully, redirect, throw a not-found condition, or surface an error boundary. Even though they are not event APIs, they explain why observation APIs exist: routing is a stateful process that can include matching, loading, blocking, redirecting, error handling, and rendering. Router state and events are the vocabulary for tracking those transitions.
Practical Usage Guidance
When creating a Router app, start with the route tree and let that tree drive the rest of the configuration. Use createRouter as the construction point, keep the options typed through the public RouterOptions Type when you need reusable configuration, and pass the resulting instance to the appropriate framework integration. After that, prefer the most specific hook for component reads. For example, location-aware UI should use the location hook, route data should use loader-data hooks, and generic shell state can use useRouterState when it truly needs router-level state.
Sources: docs/router/api/router.md
For reusable libraries, templates, or internal platform code, keep public type names in the API index visible in your own code. Accept or infer the Router Type where a real router instance is needed, use RouterOptions Type when wrapping router construction, and consult RouterEvents Type before wiring observers. This makes your code easier to align with the upstream Router reference and prevents accidental dependence on private implementation details. The Router API page is also the navigation hub for related reference pages, so it is the right starting point when upgrading or auditing router-facing abstractions.
A practical next step is to read this page together with the route, hook, and navigation references. Router options and state are easiest to understand after you know what the configured route tree can express. If you are debugging a production app, combine useRouterState with the Devtools page and the debug guide. If you are designing a reusable app shell, review route context, navigation APIs, and error/redirect utilities so that your shell observes the router without duplicating route-level behavior.