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 />)

[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.

[LeeVancee]

seem that not work in tanstack start

[miraclemenikelechi]

i am trying to make the URL '/login' where '/login' and '/signup' shares the same layout but this solution does not work for me, it redirects to '/' (the index route) each time i hit '/login' or '/signup'

my dir looks like

routes
├── index.tsx
├── (authentication)
│   ├── layout.tsx
│   ├── login.tsx
│   └── signup.tsx

[mathiasrscom]

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

[Eigilak]

Anybody got any luck with also naming the layout files to be lazy?

So you can load the routes with layout.lazy.tsx?

[CanRau]

Maybe this helps someone, got it working and shared some details here #1457 (comment)

[bangonkali]

Just adding my own opinion on this one and it would be good if I can get constructive feedback whether my approach makes sense or just bad 😅.

Gist is, I have since stopped using _xxxx.tsx and __root.tsx for rendering ui layout purposes. I opted to primarily use it for context building purposes ie authentication, enriching context, enriching routing or data loading as you go deeper to child routes.

My approach is to use shared components for UI rendering layout purposes.

This approach provides clear separation of concerns.

This is not a decision that was taken from the onset but a realization that came after working on a project for a while. I found out that separating the layout from the route file made it easier to manage the layout and the route file separately. It also made it easier to manage layouting indepent of routing.

At first I was really confused as well, and even my code base has vestiges of the initial appraoch which I could not easily take down yet. But I think this new apprach provides the separation of concerns i needed and is worth it.

Just getting a level of assurance from a compiling project such that all the routes match together is what I'm really aiming for. The benefit I'm gaining from using typed routing with tanstack-router is what I really was going for anyway, otherwise I should have remained with the traditional frameworks whose mental model I'm already familiar with, however in this case I'm somewhat satisfied with the result 😅.

Sample Structure:

Root

src/routes/__root.tsx

Just for establishing context structure. There are no UI Design related components here.

interface RouterContext {
  auth: AuthContextProps;
  tenant?: components["schemas"]["TenantInfo"];
  workflow?: components["schemas"]["WorkflowInfo"];
}

export const Route = createRootRouteWithContext<RouterContext>()({
  notFoundComponent: ErrorNotFoundPage,
  component: () => {
    return <Outlet />;
  },
});

Private Routes

src/routes/_private.tsx

Just for making sure the user is authenticated. Since it has _ on _private then it means it will not appear on the route string in the browser. Content redacted at least for this route. Everything below src/routes/_private route are authenticated as result.

Tenant Id

In addition to being private, I just make sure everthing below this route has information regarding the current tenant. Please note that since tenantId is a search parameter, i resorted to using (tenantId) to provide visual cues that it is a search parameter instead of the regular $tenantId for a route parameter. All child pages in my app requires tenantId as a search parameter so all subfiles under (tenantId) now assumes the search parameter tenantId is present and that tenant context has already been pre-resolved.

src/routes/_private/dashboard/_layout/(tenantId)/_layout.tsx

import { queryClient } from "@/config";
import { clientProvider } from "@/lib/openapi/client-provider";
import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";
import { zodValidator } from "@tanstack/zod-adapter";
import { z } from "zod";

const tenantSearchSchema = z.object({
  tenantId: z.string().uuid(),
});

type TenantSearch = z.infer<typeof tenantSearchSchema>;

export const Route = createFileRoute(
  "/_private/dashboard/_layout/(tenantId)/_layout"
)({
  beforeLoad: async ({ search, context }) => {
    const searchTyped = search as TenantSearch;
    try {
      const response = await queryClient.ensureQueryData(
        clientProvider().queryOptions("get", "/api/Tenant/{tenantId}", {
          params: { path: { tenantId: searchTyped.tenantId } },
        })
      );

      if (response) {
        context.tenant = response;
        return {
          tenant: response,
        };
      }
    } catch (error) {
      // Just for my sanity's sake since I'm also working on the backend at the same time.
      console.log(JSON.stringify(error, null, 2));
    }

    // Note: I had tried to redirecting routes from here before but I did not like how it turned out. So I passed the tenant to the context and let the child routes handle the redirection in case it is undefined.
    context.tenant = undefined;
    return {
      tenant: undefined,
    };
  },
  validateSearch: zodValidator(tenantSearchSchema),
  component: RouteComponent,
});

function RouteComponent() {
  const { tenant } = Route.useRouteContext();

  if (!tenant) {
    return <Navigate to="/error" replace />;
  }

  return <Outlet />;
}

All the pages below (tenantId) get the tenant context. In this route example below, when the user creates a new Workflow object, the tenant object is already passed down to the new workflow page.

And also, <DefaultLayoutWrapper> is a shared component that provides a consistent layout on select pages depending on how they should be rendered. This alludes to my statement that I have since stopped using _xxxx.tsx and __root.tsx for rendering ui layout purposes and instead opted to use a shared component for layout purposes.

src/routes/_private/dashboard/_layout/(tenantId)/_layout/workflow/_layout.new.lazy.tsx

import { NewWorkflowPage } from "@/components/pages/NewWorkflowPage";
import { DefaultLayoutWrapper } from "@/components/shared/DefaultLayoutWrapper";
import { createLazyFileRoute } from "@tanstack/react-router";

export const Route = createLazyFileRoute(
  "/_private/dashboard/_layout/(tenantId)/_layout/workflow/_layout/new"
)({
  component: RouteComponent,
});

function RouteComponent() {
  const { tenantId } = Route.useSearch();
  const { tenant } = Route.useRouteContext();
  console.log(JSON.stringify(tenant, null, 2));

  return (
    <DefaultLayoutWrapper>
      <NewWorkflowPage tenantId={tenantId} />
    </DefaultLayoutWrapper>
  );
}

One can use the same pattern for situation wherein you need pagination ie page and pageSize as search parameters. Just use (paginated) instead to qualify that the route is paginated with resolution for both page and pageSize built in.

Workflow Id

In addition to being private and having tenant context, I just make sure everthing below this route has information regarding the current workflow.

src/routes/_private/dashboard/_layout/(tenantId)/_layout/workflow/$workflowId/_layout.tsx

import { queryClient } from "@/config";
import { clientProvider } from "@/lib/openapi/client-provider";
import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";

export const Route = createFileRoute(
  "/_private/dashboard/_layout/(tenantId)/_layout/workflow/$workflowId/_layout"
)({
  beforeLoad: async ({ params, context }) => {
    try {
      const workflowId = params.workflowId;
      const response = await queryClient.ensureQueryData(
        clientProvider().queryOptions("get", "/api/Workflow/{workflowId}", {
          params: { path: { workflowId: workflowId } },
        })
      );

      if (response) {
        context.workflow = response;
        return {
          workflow: response,
        };
      }
    } catch (error) {
      console.log(JSON.stringify(error, null, 2));
    }

    // Notice. Same as above, I let the child routes handle the redirection in case it is undefined. I had tried to redirecting routes from here before but I did not like how it turned out. Maybe I'm just doing it wrong.
    context.workflow = undefined;
    return {
      workflow: undefined,
    };
  },
  component: RouteComponent,
});

function RouteComponent() {
  const { workflow } = Route.useRouteContext();
  if (!workflow) {
    return <Navigate to="/error" replace />;
  }

  return <Outlet />;
}

Both the following routes below get the object tenant and workflow context.

src/routes/_private/dashboard/_layout/(tenantId)/_layout/workflow/$workflowId/_layout.index.lazy.tsx
src/routes/_private/dashboard/_layout/(tenantId)/_layout/workflow/$workflowId/_layout.playground.tsx

As in the following example:

export const Route = createLazyFileRoute(
  "/_private/dashboard/_layout/(tenantId)/_layout/workflow/$workflowId/_layout/"
)({
  component: RouteComponent,
});

function RouteComponent() {
  // both information already available due to upper level routes passing them down.
  const { workflow, tenant } = Route.useRouteContext();
  const jobName = workflow.jobName as JobNameType;
  return (
    <>
      <DefaultLayoutWrapper>
        {jobName === "Job1" ? (
          <Job1Cards workflow={workflow} tenant={tenant} />
        ) : jobName === "Job2" ? (
          <Job2Cards workflow={workflow} tenant={tenant} />
        ) : undefined}
      </DefaultLayoutWrapper>
    </>
  );
}

Public Routes

All these routes below use _public.tsx as the root layout. Depending on the layout rendering guidelines they can have UI related layout defined on _public.tsx or they can be defined independenly per page, it's up to you. I had become lazy at this part so I just implement design on _public.tsx and just use it as a layout for all public pages.

src/routes/_public.tsx
src/routes/_public/index.lazy.tsx
src/routes/_public/about.lazy.tsx
src/routes/_public/documentation.lazy.tsx
src/routes/_public/playground.lazy.tsx

Outcome

As a result as per vscode intellisense I have the following valid routes:

And with the understanding that everything below (tenantId) which includes all of ../workflow/* requires the tenantId query parameter and has the tenant context pre-resolved.

To be able to press tab and get an intellisense was what I really wanted and the only reason for using this library.
😂

To Anwer the OP's Question

I would just totally avoid using _auth.tsx for ui layout rendering purposes. And i would just use shared components for layouting purposes on specific pages that need them.

_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 have shared <DefaultLayoutWrapper> below as an example of a shared layout component that can be used on multiple pages. One can make other shared layout components as needed to support different classes of pages. As a result generally avoiding _xxxx.tsx for layouting purposes.

Example Shared Layout Component

import React from "react";
import { MenuBar } from "./MenuBar";
import { TanStackRouterDevtools } from "@tanstack/router-devtools";
import { DiagnosticsCard } from "./DiagnosticsCard";
import { DiagnosticsWrapper } from "./DiagnosticsWrapper";

export type DefaultLayoutWrapper = {
  children: React.ReactNode;
};

export const DefaultLayoutWrapper: React.FC<DefaultLayoutWrapper> = ({
  children,
}) => {
  return (
    <>
      <div className="container mx-auto p-4 space-y-6 max-w-4xl">
        <MenuBar />
        {children}
        <DiagnosticsWrapper>
          <TanStackRouterDevtools />
          <DiagnosticsCard />
        </DiagnosticsWrapper>
      </div>
    </>
  );
};

Conclusion

I have since stopped using _xxxx.tsx and __root.tsx for rendering ui layout purposes (except when I'm being lazy or I know is temporary) and as a result I have been able to work faster without intermixing routing and design layout concerns.

I'm hoping to get counterpoints as well to help validate my opinion on this matter, please provide feedback if this is a bad idea. 😅

[miraclemenikelechi]

more like NextJS layout approach 👍