Route-level code splitting
A route component should be downloaded only when its route is needed.
TanStack · Function
lazyRouteComponent
Creates a one-off, code-split TanStack Router route component. The returned lazy component can be preloaded, and an optional export name supports named exports.
How it works
Pass an importer that resolves to a module containing the route component. The function returns a React.lazy component and adds a preload method, while an optional export name selects a named export instead of the module's default export.
Syntax
lazyRouteComponent(importer, exportName?)Parameters
| Name | Type | Description |
|---|---|---|
importer | () => Promise<T> | Function returning a promise that resolves to an object containing the component. |
exportName | string | Optional exported component name; defaults to the default export. |
Returns
A React.lazy component that can be preloaded using component.preload().
Key points
- It is intended for one-off route-level code splitting and exposes preload() for warming the component before navigation.
- The importer is a required function whose promise resolves to a module-like object containing the component.
- The optional exportName chooses the component property from the imported module.
- The result is a React.lazy component with a preload() method.
Common mistakes
- For file-based routing, prefer createLazyFileRoute rather than using this one-off component helper.
- If exportName is omitted, the imported module's default export is used.
Example: Lazy-load a route component
import { createRoute, lazyRouteComponent } from '@tanstack/react-router'
const postsRoute = createRoute({
getParentRoute: () => rootRoute,
path: '/posts/$postId',
component: lazyRouteComponent(() => import('./Post')),
})The route loads its default-exported component on demand, splitting the route component into a separate bundle.
When to use it
Preloading a future route
Navigation or interaction can begin loading a route before rendering it.
Named component exports
The component is exported by name rather than as the module default.
Interview questions
QWhat arguments does lazyRouteComponent accept?
It accepts an importer and an optional exportName. The importer must return a promise resolving to a module containing the component; exportName identifies which export to use and defaults to the default export.
Follow-up: How can the resulting component be loaded before rendering? Call its preload() method, which is exposed on the returned lazy component.
QWhat does lazyRouteComponent return?
It creates a one-off code-split route component. The returned value is a React.lazy component that supports preloading through component.preload().
Follow-up: When should this helper generally be avoided? In file-based routing, use createLazyFileRoute instead.
QHow do you lazy-load a named component export?
Use the default form when the module's component is the default export. Pass the export's name as the second argument when the component is exported by name.
Follow-up: What must the first argument provide? A function returning a promise for an object that contains the component to load.
Related
createLazyFileRoutecreateRouteReact.lazy