Render shared layout content and an Outlet for nested routes.
Application shell
TanStack · Function
createRootRoute
Creates the top-level route for a TanStack Router route tree. Configure it with route options, attach child routes, and pass the resulting tree to createRouter.
How it works
Call createRootRoute with route options to obtain the top-level route instance. Configure its component or other supported options, add child routes to form a route tree, and pass that tree to createRouter.
Syntax
createRootRoute(options?: Omit<RouteOptions, 'path' | 'id' | 'getParentRoute' | 'caseSensitive' | 'parseParams' | 'stringifyParams'>): RootRouteParameters
| Name | Type | Description |
|---|---|---|
options | Omit<RouteOptions, 'path' | 'id' | 'getParentRoute' | 'caseSensitive' | 'parseParams' | 'stringifyParams'> | Configuration for the root route, typed as RouteOptions with path, id, getParentRoute, caseSensitive, parseParams, and stringifyParams omitted. |
Returns
A new Route instance.
Key points
- Calling the function creates the top-level route object.
- Provide an options object to define the root route's behavior and presentation.
- Its options are based on RouteOptions but exclude root-inapplicable path, identity, and parent-route fields.
- The function is imported from the React Router package alongside common root-route setup utilities.
- Use addChildren on the returned instance to assemble the route tree.
- Give the constructed route tree to createRouter to configure the router.
Common mistakes
- The returned route is only the root of the tree; add child routes before using the route tree with a router.
- Pass configuration through the options object rather than trying to provide path or parent-route settings that the function excludes.
Example: Create a root route
import { createRootRoute, createRouter, Outlet } from '@tanstack/react-router'
const rootRoute = createRootRoute({
component: () => <Outlet />,
})
const routeTree = rootRoute.addChildren([])
const router = createRouter({ routeTree })
export { router }Creates a root route with an outlet, adds its child routes, and supplies the resulting tree to a router.
When to use it
Create the root node and attach child routes with addChildren.
Route-tree construction
Supply the completed route tree to createRouter.
Router initialization
Interview questions
QWhat does createRootRoute return?
It creates and returns a new root route instance. That instance can receive route options and is then used to build a route tree with child routes.
Follow-up: How is a root route used to construct a router? Add child routes with addChildren, then pass the resulting route tree to createRouter.
QWhat is the shape of the options parameter?
The function accepts an options object for configuring the root route. The documented type is RouteOptions with path, id, getParentRoute, caseSensitive, parseParams, and stringifyParams omitted.
Follow-up: Why are those fields omitted? A root route is the tree's top-level route, so those route relationships and path-specific settings are not supplied through this function.
QHow does a root route participate in rendering nested routes?
A root route commonly renders an Outlet so nested route content has a place in the layout. The root route can also be created without options when no root component is needed.
Follow-up: When should a context-specific helper be used instead? Use createRootRouteWithContext when the router must satisfy a declared context type.
Related
createRootRouteWithContextcreateRoutecreateRouterOutletRouteOptionsRootRoute