Custom Layout for Specific Routes in tanstack/router

[AndrejNemec]

Hello tanstack/router community,

I'm working on a React project where I'm using the File-Based routing feature of tanstack/router. I have a specific requirement for which I'm seeking some advice or guidance.

My project structure includes an index.tsx file, which I understand represents the root (/) route. The layout for this is determined by __root.tsx. However, I'm looking to implement a custom layout for the index.tsx page and other related pages, specifically for authentication-related routes like sign-in and sign-up.

Here's how I envision the structure:

• _auth
  • _auth.tsx <-- This should be the Layout for the routes inside _auth
  • _auth.index.tsx <-- Represents the / route (sign-in page)
  • _auth.sign-up.tsx <-- Represents the /sign-up route (sign-up page)

I want both the sign-in (/) and sign-up (/sign-up) pages to share the same layout defined in _auth.tsx. Could you please provide some insights or examples on how to achieve this in tanstack/router? Is there a specific way to define that _auth.tsx should be the layout for both these routes?

Any help or pointers towards relevant documentation would be greatly appreciated!

Thank you!

[SeanCassiere]

The route structure for layout routes is as follows:

src/routes/
  _auth/
    index.tsx
    sign-up.tsx
  __root.tsx
  _auth.tsx // <- this is the layout file

You can see it in action in the Basic File-Based example.

[julianogwarp]

is there a way to remove the __root fixed links top bar just for the signup page ?

[SeanCassiere]

You could move could either conditionally check the current location and hide the top bar on the root route, or you could move your pages into layout routes and render the correct components/containers based on that.

[nilshartmann]

Is there any way to put the layout file inside a route sub-directory?:

src/routes
  auth/
   _layout.tsx  // <-- would be nice to have: applied for /auth/ and /auth/sign-up
   index.tsx
   sign-up.tsx

The only working way I found for this case is:

src/routes
  auth.tsx  // <-- applied for /auth/ and /auth/sign-up
  auth/
    index.tsx
    sign-up.tsx

But i find it somehow confusing to have both auth.tsx as file and auth as folder.

Maybe it's this bug that makes my first example not working: #1150 ?

[SeanCassiere]

If I understand you correctly, you are trying to achieve this?

src/routes
  auth/_layout.tsx
  auth/_layout/sign-up.tsx
  index.tsx

If so, yes the route generator is currently bugged as mentioned in #1150.

You can check out the last point in my comment on the issue, that lets you get around this till a fix is released.

Edit: However, if your question is regarding whether you can nest the layout file inside the layout folder, then that is not possible. The _layout.tsx is the route configuration, whilst the _layout/ folder contains the routes for that particular layout.

[nilshartmann]

Thanks @SeanCassiere ! I thougt about the latter: I have a "regular" route that has its own layout file, for example as in Next.js https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#layouts)

[AndrejNemec]

Is it possible to use a layout with route groups as well? So that I could have a layout for the entire group of routes?

(auth)/index.tsx <--- for the 'auth' group

[rieger-jared]

Is there any way to put the layout file inside a route sub-directory?:

src/routes
  auth/
   _layout.tsx  // <-- would be nice to have: applied for /auth/ and /auth/sign-up
   index.tsx
   sign-up.tsx

The only working way I found for this case is:

src/routes
  auth.tsx  // <-- applied for /auth/ and /auth/sign-up
  auth/
    index.tsx
    sign-up.tsx

But i find it somehow confusing to have both auth.tsx as file and auth as folder.

Maybe it's this bug that makes my first example not working: #1150 ?

Plus one for this too. I'm coming from Nextjs where it's common to have a layout file for that dir and it's children. I like the way they implemented as @nilshartmann suggested

src/routes
  auth/
   _layout.tsx  // <-- would be nice to have: applied for /auth/ and /auth/sign-up
   index.tsx
   sign-up.tsx

I think this is far clearer than the current alternative of

src/routes
  auth.tsx  // <-- applied for /auth/ and /auth/sign-up
  auth/
    index.tsx
    sign-up.tsx

or worse yet

src/routes
 auth/_layout.tsx
 auth/_layout/sign-up.tsx
 index.tsx

The last one especially is weird imo.

[julianpera]

What if a want to make auth part of the URL? If I understand correctly, I would have to nest the whole _auth inside an auth folder like this:

src/routes/
  auth
    _layout
      foo.tsx
    _layout.tsx
  index.tsx

I also believe something like this is much more cleaner:

src/routes/
  auth -> or (auth), according to whatever you want "auth" to be part of the url or not
    _layout.tsx
    foo.tsx
  index.tsx

[SeanCassiere]

What if a want to make auth part of the URL? If I understand correctly, I would have to nest the whole _auth inside an auth folder like this:

If you want to have auth as part of the URL as a layout, you can either use the method you proposed or prefix the filename with auth.

src/routes/
  _layout.tsx
  _layout/
    auth.foo.tsx <- becomes `/auth/foo`

Concerning changing how the router-generator works, we are currently happy with how it conceptualizes the relationships between the file-tree and the route-tree. Each file in the file-tree corresponds to a part of the actual route-tree, thereby letting you better understand how the router's route-tree is built, and still allowing you the customizability of each component (since some annoying parts are obscured when not using code-based routing).

Tanner is making huge efforts to reduce the verbosity of code-splitting pages, but I don't see us making such large breaking changes on how the file-based routing functions anytime soon.

Even in V2, we'd likely keep much of how the existing file-based routing works, as it currently allows the highest amount of flexibility at the cost of having to possibly create a couple more files or folders. These extra files and folders do not get touched unless the user intentionally needs to make a change. We are happy with this.

[MariuzM]

Sorry but its not about possibly create a couple more files but you literally will have to create file and folder just to use a single file/route with layout all the time. If you have a big project with many changing layouts this will get complex fast and hard to maintain

[MariuzM]

This here explains it all and if v2 will have same structure as v1 a lot of people will be unhappy and will look for alternatives like React Router v7 and then most likely they wont come back to TSR because their stack already has been built with RR7.

Please consider having _layout file only in v2

[MariuzM]

Going back I’ve seen @cathaysia mentioned to use route.tsx so its basically _layout.tsx
here is example and looks like its working fine
https://github.com/MariuzM/web-frameworks/tree/main/react-tsr/src/routes/test5

Curious to know difference between test2 and test4?

But basically this comes down, should us just use route.tsx as our layout because from file structure it make sense, no need to create extra folder. But the naming route.tsx is not i think what we are used to call a layout.tsx .

[lpkobamn]

so confusing...

[taylorhakes]

I got very confused by this as well, but in a different way. I think the docs should be clear how to use folders with pathless routes. I actually thought it worked like this based on the docs:

src/routes/
   _auth/
     index.tsx (layout component)
     foo.tsx (route inside index.tsx layout)

This is very counter intuitive based on how node JS imports work.

src/routes/
   _auth.tsx (layout component)
   _auth/
     foo.tsx (route inside _auth.tsx layout)

[abuu-u]

try to rename intex.tsx into route.tsx

[SeanCassiere]

The layout component for a pathless route must be on the same level as the identifiers before its children.

src/routes/
	_auth.tsx
	_auth/
		index.tsx

We do show this in the docs in the file-based routing guide and the routing concepts guide, not to mention in our examples (with exception to the quickstart).

What do you think we could do to better call this out in the docs? We figured examples both in the docs and hosted stackblitz was the way to go. What could be changed here (from the perspective of someone who found it difficult)?

Edit: The reason our layout/pathless routes in file-based routing does not work like Next is because our layout routes apply to multiple parent paths unlike Next which applies to a single parent paths and only its children.

[cathaysia]

I am migrate from nextjs, after read this discussion, it seems @tanstack/router's layout.tsx should be route.tsx, so the layout of your project should be:

.
├── __root.tsx
├── path1
│   ├── index.tsx
│   └── route.tsx
├── path2
│   ├── index.tsx
│   └── route.tsx
├── index.tsx
└── settings
    ├── opt1.tsx
    ├── index.tsx
    └── route.tsx

compare to nextjs's app route:

.
├── layout.tsx
├── path1
│   ├── layout.tsx
│   └── page.tsx
├── path2
│   ├── page.tsx
│   └── layout.tsx
├── page.tsx
└── settings
    ├── app
    │    └── page.tsx
    ├── page.tsx
    └── layout.tsx

[cathaysia]

Also, where is it mixed together? Since this is something that can be changed.

For example, this page: https://tanstack.com/router/latest/docs/framework/react/guide/file-based-routing

It first discusses two kinds of file-based route, then discusses virtual-file-route, and at the last it discusses three methods to use it.

first I think virtual-file-route is a advanced feature, and not so many people use it.

second "how to use it" should already exists in https://tanstack.com/router/latest/docs/framework/react/quick-start, so don't need repeat it again.

It would be better to put advanced features and infrequently used features in other places. The main chapters only contain some commonly used features.

[SeanCassiere]

Some points.

It first discusses two kinds of file-based route,...

Can't get around the two flavours of file-based routes here on this guide since it's the only guide for "file-based routing" as a whole. It NEEDS to be communicated that you don't need to stick to one flavour of file-based routing and that you can mix them.

...then discusses virtual-file-route...

Yup, I agree, the virtual routes content can be nuked from the file-based routing page.

...and at the last it discusses three methods to use

This doesn't happen.

first I think virtual-file-route is an advanced feature, and not so many people use it.

This is something coming with RRv7 and we can't dismiss the hype behind the feature. That being said, with the code example for it only being contained to its own page, it'll make the file-based routing guide much easier to read.

second "how to use it" should already exists in tanstack.com/router/latest/docs/framework/react/quick-start, so don't need repeat it again.

We can't take for granted that someone has gone to the quick start page and then come to another guide. Flow is never guaranteed, so there inevitably will be some duplication between content in a "quick start"/"getting started" guide vs the bonafide guide on a certain topic.

It would be better to put advanced features and infrequently used features in other places. The main chapters only contain some commonly used features.

What would you consider to be "main" here?

[SeanCassiere]

nextjs has a button to switch app/page router document, maybe tanstack can also do this? It should makes document more clear.

Could be looked into, but it'd require a decent bit of work being put into the tanstack.com repo. 😅 Busy with Router at the moment.

[SeanCassiere]

Yup, I agree, the virtual routes content can be nuked from the file-based routing page.

Fixed #2497

[cathaysia]

What would you consider to be "main" here?
I think the main chapter should contains:

1. How to makes a smallest router work.
2. The main concept of router, such index.tsx, $id.tsx, nested router, parentless router, most people will only need these.
3. some hooks and components, such <Link>, <Navigate>, redirect, useRouterState() and etc.

In most scenarios, I only need to master this knowledge.

Could be looked into, but it'd require a decent bit of work being put into the tanstack.com repo. 😅 Busy with Router at the moment.

Yes! router always the most important. :)

Fixed #2497

Pure awesome. What's a wonderful community!!!

[p0wder]

I second the NextJs way but once I figured out a decent way to implement layouts it's not too bad. We just need more examples.

Check out my solution for this.

routes
├── index.tsx
├── about.tsx
├── (unpathed-for-layout)
│   ├── layout.tsx
│   ├── layout.child1.tsx
│   └── layout.child2.tsx

Inside of layout.tsx should use <Outlet /> to render child 1 and 2 based on which path is selected.

[MariuzM]

adding layout to each file is not great.
just use routes.tsx file as layout thats it

[olehakon]

I found a workaround:

In vite.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { TanStackRouterVite } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
      TanStackRouterVite({
          routeToken: "layout" // <-- Add this line
      }),
      react()
  ],
});

Then I can define my routes as following:

/about
--> index.tsx
--> layout.tsx (component with <Outlet />)

[m16bappi]

Yes! it's worked for me ❤️

[kirankunigiri]

This is a great solution, thank you! Works perfectly.

[alysonvilela]

nice!

[gnllucena]

THIS IS THE ANSWER!

[jashwant]

What some of us want is route.tsx file.

From docs

.route.tsx File Type
When using directories to organize your routes, the route suffix can be used to create a route file at the directory's path. For example, blog.post.route.tsx or blog/post/route.tsx can be used at the route file for the /blog/post route. This can be configured via the routeToken configuration option, see options.

It's confusing, as it definitely serves the purpose of what we are expecting from _layout.tsx.

As olehakon suggested, we can rename routeToken to 'layout' or '_layout' but not sure why it is named 'route' as default.

[mathiasrscom]

Thanks for this thread! It was exactly what I need to move forward with Tanstack :)