Routes API Reference

Purpose and Scope

This reference explains the route-definition surface used by TanStack Router when an application builds a route tree. A route tree is the typed hierarchy of route instances that the router matches against the current location, uses to infer params and search schemas, and renders through nested components. The central type on this page is RouteOptions, because it describes the options accepted when creating a route. The page also covers legacy class constructors and route masks so that maintainers can understand existing code while preferring the newer factory functions in new work.

Sources: docs/router/api/router/RouteOptionsType.md, docs/router/api/router/RouteClass.md, docs/router/api/router/RootRouteClass.md, docs/router/api/router/FileRouteClass.md, docs/router/api/router/RouteMaskType.md

The public Router API documentation lists both function-based creators, such as createRoute, createRootRoute, createFileRoute, and createRouteMask, and older class APIs, such as Route, RootRoute, and FileRoute. The class pages in this repository explicitly mark those classes as deprecated and point readers toward the function APIs. Treat the class entries here as compatibility references for reading or migrating existing applications, not as the primary authoring style for new routes.

Relevant Source Files

• docs/router/api/router/RouteOptionsType.md - Defines the documented route option object, including parent linkage, path or id identity, rendering components, search validation, search middleware, and deprecated params parsing hooks.
• docs/router/api/router/RouteClass.md - Documents the deprecated Route class constructor, its RouteOptions input, return value, and a code-based example using useLoaderData.
• docs/router/api/router/RootRouteClass.md - Documents the deprecated RootRoute class, including the subset of route options valid for a root route and an example that builds a route tree before calling createRouter.
• docs/router/api/router/FileRouteClass.md - Documents the deprecated FileRoute factory class for file-based routes, including the generator-managed path argument, .createRoute method, and required Route export name.
• docs/router/api/router/RouteMaskType.md - Defines the RouteMask type as an extension of ToOptions with route-tree support and optional reload unmasking behavior.

RouteOptions Contract

RouteOptions is the common configuration object for a route. It requires getParentRoute so the child route can connect to its parent and the router can build a fully typed tree. It also requires a route identity: use path for a route that matches a pathname segment, or use id when defining a pathless layout route. A pathless layout route does not match the location pathname directly; instead, its children are flattened into the parent for matching while still allowing layout and configuration composition.

Sources: docs/router/api/router/RouteOptionsType.md

Rendering options describe what the router should show during normal, error, pending, and not-found states. component accepts a RouteComponent or LazyRouteComponent and defaults to <Outlet />, which lets child routes render through the parent. errorComponent, pendingComponent, and notFoundComponent also accept route or lazy components, with defaults coming from the corresponding router-level defaults. This means route authors can override behavior locally without redefining global fallbacks for every branch of the route tree.

Search handling is part of the route contract rather than an afterthought. validateSearch receives raw search params from the current location and returns the parsed route search schema. If validation throws, the route enters an error state and the error is thrown during render; otherwise, the returned type is inferred into the rest of the router. The docs also describe the SearchSchemaInput tag, which lets <Link /> and navigate() accept a different input type than the parsed output, useful for optional incoming search values.

Search middlewares run when the router generates links for a route or its descendants. Each middleware receives the current search object and a next function, allowing middleware to transform search params in sequence. This is separate from validateSearch: validation parses a matched URL, while middleware influences generated navigation targets. The same source page also documents deprecated parseParams and stringifyParams hooks, with guidance to use params.parse and params.stringify instead when route params need conversion.

Compact RouteOptions Reference

Deprecated Route and RootRoute Classes

The Route class implements the route API and creates route instances from a single RouteOptions object. Its constructor returns a new Route instance that can participate in a route tree. The documented example creates an index route with getParentRoute, path, a loader, and a component that reads data through the route instance’s useLoaderData helper. Because the page includes a caution that Route will be removed in the next major version, prefer createRoute for new code.

Sources: docs/router/api/router/RouteClass.md

import { Route } from '@tanstack/react-router'
import { rootRoute } from './__root'
 
const indexRoute = new Route({
  getParentRoute: () => rootRoute,
  path: '/',
  loader: () => {
    return 'Hello World'
  },
  component: IndexComponent,
})
 
function IndexComponent() {
  const data = indexRoute.useLoaderData()
  return <div>{data}</div>
}

RootRoute extends Route, but its constructor accepts a narrower option shape. The root has no parent and does not need a path, id, or getParentRoute; the documented type omits those fields along with caseSensitive, parseParams, and stringifyParams. The example constructs a root route with an Outlet, adds child routes through addChildren, and passes the resulting routeTree to createRouter. That sequence shows the root route’s role as the top-level assembly point for code-based route trees.

Sources: docs/router/api/router/RootRouteClass.md

import { RootRoute, createRouter, Outlet } from '@tanstack/react-router'
 
const rootRoute = new RootRoute({
  component: () => <Outlet />,
  // ... root route options
})
 
const routeTree = rootRoute.addChildren([
  // ... other routes
])
 
const router = createRouter({
  routeTree,
})

When maintaining legacy code, the practical migration rule is to preserve the same route option intent while changing the construction API. A Route constructor call maps conceptually to createRoute, and a RootRoute constructor call maps to createRootRoute. Keep the same parent relationships, route identity, loader usage, and component boundaries, then verify type inference at the places that consume route data. The deprecation notices are explicit, so avoid introducing new class-based routes in application or example code.

FileRoute Class for File-Based Routes

FileRoute is also deprecated, but it documents important file-based routing conventions. Its constructor receives the full path of the file that the route will be generated for. The docs state that this string literal is required but automatically inserted and updated by the tsr generate and tsr watch commands. That distinction matters: application authors configure route behavior, while the Router generator owns the generated path identity needed to connect the file to the route tree.

Sources: docs/router/api/router/FileRouteClass.md

After construction, FileRoute exposes .createRoute(options). Those options are Omit<RouteOptions, 'getParentRoute' | 'path' | 'id'>, because file-based routing derives parentage and identity from file placement rather than handwritten configuration. The resulting value is a Route instance that can be inserted into the generated route tree. The source documentation also includes an operational requirement: for tsr generate and tsr watch to work properly, the file route instance must be exported from the file using the Route identifier.

import { FileRoute } from '@tanstack/react-router'
 
export const Route = new FileRoute('/').createRoute({
  loader: () => {
    return 'Hello World'
  },
  component: IndexComponent,
})
 
function IndexComponent() {
  const data = Route.useLoaderData()
  return <div>{data}</div>
}

For new file-based routes, use the modern createFileRoute function rather than the class shown above. The class reference is still useful when reviewing generated or older code because it makes the division of responsibility clear. File paths, parent routes, and ids belong to the file-route generation system; route authors provide loader, component, search, error, pending, and not-found behavior. That model is what enables typed route trees without repeating parent and path configuration inside every route module.

RouteMask Type

A RouteMask describes a masked navigation target. The type extends ToOptions, so it starts with the same destination-oriented options used by link and navigation APIs. It then adds options.routeTree, which is required and tells the mask which route tree it supports, and options.unmaskOnReload, an optional boolean that removes the mask when the page reloads. The type is normally paired with the route-mask creation API listed in the Router API index.

Sources: docs/router/api/router/RouteMaskType.md

Route masks are useful when an application wants the displayed URL and matched route behavior to diverge in a controlled way, such as modal-style flows or alternate presentation URLs. The documented type is intentionally compact: it does not define rendering, validation, loaders, or components. Instead, it connects navigation options to a concrete route tree and optionally controls reload behavior. When working with masks, first confirm that the underlying route tree can satisfy the destination, then decide whether reloads should preserve the masked URL or reveal the unmasked location.

Compact RouteMask Reference

System-to-Code Mapping and Next Steps

Use this page when you need to distinguish route configuration from route creation. RouteOptions defines the shape of a route’s behavior and type inference surface. Route, RootRoute, and FileRoute show older construction APIs that are still documented for compatibility but marked for removal. RouteMask documents a navigation-oriented type that composes with ToOptions rather than defining route rendering. Together, these references explain the data structures behind the function-based APIs most applications should use today.

For implementation work, start with the modern creator functions that correspond to the class or type you are reading about: createRoute for normal code-based routes, createRootRoute for the root, createFileRoute for file route modules, and createRouteMask for masks. Then cross-check the more focused guides for file-based routing, navigation, search params, and error handling. If you are migrating legacy code, update one route branch at a time and verify loader data, search typing, params typing, and generated route-tree output after each change.