In TanStack Start, a pathless layout route wraps child pages in shared UI without adding a URL segment. In file-based routing, prefix its filename with an underscore, then place <Outlet /> in the layout where the matched child page should appear. For example, an _app layout can wrap routes that still resolve to /dashboard and /settings.
How layouts fit into TanStack Start routing
TanStack Start uses TanStack Router: the route tree nests matched route components, so a parent route can render shared interface around its child route. A layout is useful for elements such as navigation, a sidebar, or route-level logic that should apply to several pages.
The root route, conventionally src/routes/__root.tsx, is the top route and is always matched. Start’s routing guide describes it as having no path of its own; it is the natural place for document-level structure. A layout is a separate route layer within that tree.
What makes a layout route pathless?
A pathless layout participates in the component hierarchy but does not contribute a URL segment. In file-based routing, the leading underscore identifies this kind of route. The rest of its ID—such as _app—identifies the route to the router, but is not inserted into child URLs.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors#1 Best Overall
For example, this file arrangement creates a shared layout around two pages:
src/routes/
__root.tsx
_app.tsx
_app.dashboard.tsx
_app.settings.tsxThe _app route can wrap the dashboard and settings routes while their URLs remain /dashboard and /settings. The underscore affects route structure, not the visible URL.
Where to put Outlet
<Outlet /> is the insertion point for the next potentially matching child route. Put it inside the layout component at the position where the child page should render. It is not a route or a URL token; it is a component in the parent route’s rendered tree. If no child route matches, the outlet renders nothing.
import { Outlet, createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/_app')({
component: AppLayout,
})
function AppLayout() {
return (
<div>
<nav>{/* shared navigation */}</nav>
<main>
<Outlet />
</main>
</div>
)
}Here, the navigation is shared, while the matched child page fills the main area. The route ID passed to createFileRoute corresponds to the file-based route; the router tooling generates and maintains the route tree in the documented setup.
Recommended Free Tools
Pathless layouts compared with other route concepts
| Route concept | URL effect | What it does | Dynamic path segments |
|---|---|---|---|
Root route (__root.tsx) |
Has no path of its own | Top-level route, always matched; suitable for document-level structure | Not applicable as a path segment |
| Ordinary layout route | Its path contributes to matching child URLs | Wraps child routes with shared UI or logic | Can match path segments, subject to its route definition |
Pathless layout route (_app.tsx) |
Adds no segment | Wraps child routes without requiring a URL prefix | Cannot itself match a dynamic path segment |
| Grouped routes | Grouping alone does not change the path hierarchy | Organizes routes; do not assume it provides the wrapper of a layout | Depends on the routes inside the group |
<Outlet /> |
Does not affect the URL | Renders the next potentially matching child in the current route component | Not applicable |
Can a pathless layout capture a dynamic parameter?
No. A pathless layout does not match URL segments, so it cannot itself capture a parameter such as a post ID. The Router guide specifically rules out a dynamic pathless directory such as _$postId/. Use a path-bearing dynamic route to match the parameter, and put a pathless wrapper at a suitable parent level if the pages also need shared UI.
How the route files become a route tree
In the documented file-based setup, TanStack Router’s supported bundler plugin or CLI generates the route configuration from the route files. Treat those files and conventions as the inputs; do not manually maintain the generated route tree as though it were the source of truth. For implementation details, consult the TanStack Start routing guide, the TanStack Router routing concepts guide, the file naming conventions, and the file-based routing guide.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
