How do layouts work with the router?

[rahiparikh]

Hi, I'd like to start by thanking you for building the router - it is great and super nice.

I am trying to understand how router (v1.4.2) + layouts work. If you can help me learn more, it would be great.

I have the following file-system structure:

.
├── __root.tsx
├── _layout.tsx
├── auth
│   ├── _layout.tsx
│   └── index.tsx
├── dash
│   ├── _layout.tsx
│   └── index.tsx
└── index.tsx

The code in ./_layout.tsx:

import { Link, Outlet, FileRoute } from '@tanstack/react-router'


function LayoutComponent() {
  return (
    <div>
      <div>I'm a layout</div>
      <div>
        <Outlet />
      </div>
    </div>
  )
}

export const Route = new FileRoute('/_layout').createRoute({
  component: LayoutComponent,
})

The code in ./dash/_layout.tsx:

const Layout = () => {
  return (
    <div>
      Layout
      <Outlet />
    </div>
  );
};

export const Route = new FileRoute('/dash/_layout').createRoute({
  component: Layout,
});

This generates the following routeTree.gen.ts.

import { Route as rootRoute } from './../pages/__root'
import { Route as LayoutImport } from './../pages/_layout'
import { Route as IndexImport } from './../pages/index'
import { Route as DashIndexImport } from './../pages/dash/index'
import { Route as AuthIndexImport } from './../pages/auth/index'
import { Route as DashLayoutImport } from './../pages/dash/_layout'
import { Route as AuthLayoutImport } from './../pages/auth/_layout'

const LayoutRoute = LayoutImport.update({
  id: '/_layout',
  getParentRoute: () => rootRoute,
} as any)

const IndexRoute = IndexImport.update({
  path: '/',
  getParentRoute: () => rootRoute,
} as any)

const DashIndexRoute = DashIndexImport.update({
  path: '/dash/',
  getParentRoute: () => rootRoute,
} as any)

const AuthIndexRoute = AuthIndexImport.update({
  path: '/auth/',
  getParentRoute: () => rootRoute,
} as any)

const DashLayoutRoute = DashLayoutImport.update({
  path: '/dash/layout',
  getParentRoute: () => rootRoute,
} as any)

const AuthLayoutRoute = AuthLayoutImport.update({
  path: '/auth/layout',
  getParentRoute: () => rootRoute,
} as any)
declare module '@tanstack/react-router' {
  interface FileRoutesByPath {
    '/': {
      preLoaderRoute: typeof IndexImport
      parentRoute: typeof rootRoute
    }
    '/_layout': {
      preLoaderRoute: typeof LayoutImport
      parentRoute: typeof rootRoute
    }
    '/auth/_layout': {
      preLoaderRoute: typeof AuthLayoutImport
      parentRoute: typeof rootRoute
    }
    '/dash/_layout': {
      preLoaderRoute: typeof DashLayoutImport
      parentRoute: typeof rootRoute
    }
    '/auth/': {
      preLoaderRoute: typeof AuthIndexImport
      parentRoute: typeof rootRoute
    }
    '/dash/': {
      preLoaderRoute: typeof DashIndexImport
      parentRoute: typeof rootRoute
    }
  }
}
export const routeTree = rootRoute.addChildren([
  IndexRoute,
  LayoutRoute,
  AuthLayoutRoute,
  DashLayoutRoute,
  AuthIndexRoute,
  DashIndexRoute,
])

Should the layouts in auth and dash directories be configured to have their own paths or should they be treated differently?

Thanks!

[Pixelycia]

Hello, answer a bit late, but for a future seekers will write what I found, because documentation lack about layouts mechanics. There are at least 2 options of organising folders to use layouts:

Option 1:

.
├── auth
│   ├── _layout.tsx
│   └── _layout.index.tsx

Option 2:

.
├── auth
│   ├── _layout.tsx
│   └── _layout
│       └── index.tsx

So as you see we should intentionally mark which layout we want to use. Inside layouts use <Outlet /> component to render child component. For examples above link remains the same: /auth. Hope it will help.

[schiller-manuel]

because documentation lack about layouts mechanics

what's missing? can you provide a PR to add the missing parts?

[0xrasla]

Thanks! its working for me

[d-a-s]

I think you can also use:

I-- auth/
    I--- route.tsx               # Layout (includes child components with <Outlet />)
    I--- index.tsx               # /auth (uses layout from auth/route.tsx)
    I--- confirm/
             I-- index.tsx       # /auth/confim (uses layout from auth/route.tsx)

Actually there is a bug with route.tsx, so this doesn't work correctly. Currently, auth/index.tsx would actually be mapped to path /, and auth/confirm/index.tsx would be mapped to /confirm/. See PR for details

#1835

[TannerBarcelos]

Option 2 worked for me. It's unfortunate that the docs don't go into this because this was impossible to know. Not only that, but the folder needs to exactly match the name of the layout file.

I have a route group called (protected) which houses all my clients pages that should render the authenticated navbar, etc. Inside that, I had initially put a _layout.tsx file to be used to render the nav and an <Outlet /> so the /dashboard, /someotherroute could be captured.

Unfortunately, unless I put all those directories into a directory called _layout directly next to _layout.tsx, nothing worked and I only saw my pages, but not the shared layout.

I think this is a little weird and pretty confusing.

[schiller-manuel]

@TannerBarcelos can you help improving the docs?

[tomredman]

For anybody else trying to understand how this work, this setup is working for me currently. I can hit the url with the correct layout applied as written in route.tsx:

• http://localhost:3000/campaigns renders <Route>
  • I have my layout code here (routes/campaigns/route.tsx), but I will have to force a redirect since it's not supposed to be a "real" page.
• http://localhost:3000/campaigns/create renders <Route><Create>
• http://localhost:3000/campaigns/overview renders <Route><Overview>

├── client.tsx
├── components
│   ├── app-sidebar.tsx
│   ├── login-form.tsx
│   ├── ...
│   └── ui
│       ├── accordion.tsx
│       ├── ...
├── css
│   └── globals.css
├── hooks
│   ├── use-mobile.tsx
├── routeTree.gen.ts
├── router.tsx
├── routes
│   ├── __root.tsx
│   ├── campaigns
│   │   ├── analytics.tsx
│   │   ├── create.tsx
│   │   ├── overview.tsx
│   │   └── route.tsx <-- this is the secret, see below for code
│   ├── index.tsx
└── ssr.tsx

// routes/campaigns/route.tsx
import { createFileRoute, Outlet } from "@tanstack/react-router";

export const Route = createFileRoute("/campaigns")({
  component: CampaignsLayout,
});

export function CampaignsLayout() {
  return (
    <div className="flex flex-col gap-4 p-4 pt-0 bg-red-500">
      <h1>Campaigns Layout</h1>
      <Outlet />
    </div>
  );
}

// routes/campaigns/create.tsx
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/campaigns/create")({
  component: RouteComponent,
});

function RouteComponent() {
  return <div>Hello "/campaigns/create"!</div>;
}

[MGSimard]

I'm gonna be honest here the file-based layout/page system feels bad big time. Considering the callout to being inspired by Next.js when it comes to the file-based routing, of all things this should've been the thing taken from Next.js:

/dashboard
- layout.tsx
- page.tsx
- /settings

This would be so incredibly simple, as it is in Next. You get a layout.tsx from /dashboard matching all child routes unless manually escaped, you get your base /dashboard page, and each subsequent page can be added in a folder. Nice, clean, quick and concise. Some people might argue creating a folder for each page.tsx is cumbersome, but in reality it's also nice for nesting page-specific component, style, asset files etc, not just the visualized routing logic.

In contrast TanStack Router's handling of Layouts is, if anything frustrating. Doesn't help that nearly every single search result in docs lead you to 404 pages. Click any result when searching "layout" and it's all 404 pages. The only relevant section in "Routing Concepts" has "TODO" as content.

As of now, it seems like the play is to have this file structure:

/dashboard
- _layout.tsx (layout + outlet inside)
- /_layout
-- index.tsx
-- /settings

Is it considered valid? Is it the best way? Who knows! Zero documentation, jesus take the wheel!

Note that while you can do the route.tsx trick in the above comment for nested pages like /dashboard, it doesn't seem to work for front-facing pages like "/", so it's a good idea to just be consistent and do _layout across the board. And even though this does work, it still feels and looks like a hack. I also don't recommend using route.tsx as a layout hack because the filename vs its purpose creates confusion.

Just compare tsrouter vs nextjs in a situation where you want separate layouts for front-facing pages (like "/", "/about-us") and dashboard pages:

Is there a cleaner or more accessible tsrouter file-based routing option for setting up layouts? Once again, who knows! Layout documentation is empty. Discussions, reddit threads, youtube comments & co do nothing but complain about tsrouter layout and its lack of documentation. Don't believe me? Google it and click on the first youtube result, read the comments. 11 months ago.

I love the TanStack stuff, but using TanStack Router's file-based routing after using Next.js for so long makes it feel hacky, not intuitive. Maybe it's me being nitpicky, but the current setup for layout inheritance both feels and looks bad. Just my two cents.

PS: The consistent passive-aggressive "Write the docs yourself" responses from maintainers when it's being brought to your attention that your documentation lacks some of the most foundational pieces of content to your library, which you chose to take responsibility for as a maintainer, also definitely doesn't look good. We're not talking about nice-to-haves here, it's a core feature. Search results not all being 404 links would be a good start.

[MGSimard]

That's basically a variation of my tsrouter example with the messy nesting inverted.

It might look good /okay/ manipulating the file order in a code block, but the reality is that your _front-facing.tsx layout file will be completely visually disconnected from its related folder, as it now shows below __root.tsx rather than next to (or in my case, within) its related group. You once again have a file structure which is inconvenient to organize & navigate as a developer. At which point the only way to clean it up is to completely avoid attempting collocation and sweep the layout files under a rug (a lot of people just make a permanently collapsed (layouts) group.

You could try restoring collocation of related files by utilizing chaining route names like:

_front-facing
  _front-facing.about-us.tsx (or /about-us/index.tsx)
  _front-facing.index.tsx
  _front-facing.tsx
(dashboard)
  dashboard.index.tsx
  dashboard.settings.tsx 
  dashboard.tsx
__root.tsx

However this removes your ability to write /settings as a folder since it falls through (dashboard), so instead you fall back to the route-as-layout hack again:

_front-facing
  /about-us/index.tsx
  index.tsx
  route.tsx
/dashboard
  /settings/index.tsx
  index.tsx
  route.tsx
__root.tsx

And despite all of this, you STILL don't have semantical file naming for layout files.

The entire point is that it is virtually impossible for tsrouter to tick the following boxes all at once (While Next.js does):

• Nicely navigateable, collocated files with immediate relations at the same nesting level
• Preserving function across the board
• Consistent conventions across the board, such as semantic file names (layout), everything using the same format without "hacks"

Notice how every permutation presented across this entire thread so far a billion hacky formats meant to accomplish the exact same outcome rather than there being one single standardized, not-a-hack solution (let alone documented) which ticks the three DX points above? While, once again, the inspiration (Next.js) for this entire file-based routing setup, does satisfy those requirements.

My hope is that this "TODO" annotated Layout section of the documentation is like that because they might be working on a better implementation of Layout files which mirrors that of Nextjs' pattern.

[Brendonovich]

To be clear the sibling file + folder approach isn't a 'hack', it's how layouts work atm in TSR. They all function the same way and is a consistent convention, and imo is nicely navigable via CTRL + P, but I can understand not feeling that way if you prefer semantic file naming.
Documentation around this approach definitely seems to be lacking, and an App Router compat mode may get built to allow semantic file names instead of file-folder pairs.

[proevilz]

I encountered a similar challenge when I first experimented with TanStack Start. Coming from Next.js, I struggled to grasp how layouts functioned, and the transition felt disorienting. Recently, I decided to kick off a standard ViteJS project with TanStack Router (TSR), only to hit a wall right away with the same layout confusion. How exactly are layouts supposed to work? It’s hard to tell. The documentation leaves much to be desired—some sections feel incomplete, and I even stumbled across pages in the Router docs that are verbatim copies from the TanStack Table docs, with content clearly unchanged and irrelevant to routing. To make matters worse, navigating the docs is a frustrating experience: the URL updates, the sidebar shifts, but the actual page content often freezes, forcing me to manually refresh just to see the right information. I believe in Tanstack's software and I'm more than sure all this will get fixed, but for at least right now, I'll use React Router.

[proevilz]

Docs have been updated: https://tanstack.com/router/latest/docs/framework/react/routing/routing-concepts#layout-routes

[austinm911]

After using TSR for quite a while I have to agree that one of the biggest pain points in my current file structures are the layouts as well. I use most of the time route.tsx with the downside that the route will become available from the navigation perspective. I think it would be great if a .layout.tsx would replace the _directive for file based routing.

Route.tsx token should be replaced by layout.tsx default token. It would help clear up the confusing some amount. No idea why route is the name when most to the time it's for a layout