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>;
}