In this lesson

Pathless Layouts Route Groups When to Use What Practice Exercise Quick Quiz

Reference

Route Naming Cheat Sheet

Pathless Layouts and Route Groups

Lesson 2 — Organizing routes without adding URL segments

You've seen _app.tsx wrapping child routes without adding a path segment. Now let's formalize pathless layouts and route groups — two tools for organizing your route tree when the URL structure alone isn't enough.

Pathless Layouts: The Underscore Prefix

A pathless layout is a route that wraps its children but does not contribute to the URL. Prefix with _:

routes/ ├── __root.tsx ├── _authenticated.tsx → pathless layout │ ├── _authenticated.index.tsx → / │ ├── _authenticated.dashboard.tsx → /dashboard │ └── _authenticated.settings.tsx → /settings └── login.tsx → /login
⚡ Key insight The underscore prefix means "don't add a path segment". _authenticated.tsx is a layout route, but /dashboard — not /_authenticated/dashboard — is the URL.

What it's for

Pathless layouts are perfect for shared behavior without URL segments:

// routes/_authenticated.tsx
import { Outlet, createFileRoute, redirect } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated')({
  beforeLoad: async ({ context }) => {
    if (!context.user) {
      throw redirect({ to: '/login' })
    }
  },
  component: AuthLayout,
})

function AuthLayout() {
  return (
    <div>
      <Header user={user} />
      <Outlet />  {/* child routes render here */}
    </div>
  )
}

Route Groups: Parentheses Prefix

A route group organizes related routes without affecting URLs. Prefix with ( and close with ):

routes/ ├── __root.tsx ├── (marketing)/ │ ├── (marketing).index.tsx → / │ ├── (marketing).about.tsx → /about │ └── (marketing).pricing.tsx → /pricing └── (app)/ ├── (app).index.tsx → / (CONFLICT!) └── (app).dashboard.tsx → /dashboard
⚠️ Warning Route groups do not create layouts. They are purely organizational. If (marketing).index.tsx and (app).index.tsx both map to /, TanStack will complain.

What it's for

Route groups are for file organization when you have many routes at the same level:

When to Use What

Pathless Layout (_)

✅ Wraps children with a component

✅ Can run code before child loads (beforeLoad)

✅ Adds to the route tree

❌ Adds a file prefix to all children

Route Group (( ))

✅ Pure organization, no component

✅ No runtime overhead

❌ Cannot wrap children or run code

❌ Adds parentheses to filenames

Rule of thumb: If you need to share code or UI across routes, use a pathless layout. If you just want tidy folders, use a route group.

Practice Exercise

You're building a mobile app with three sections:

  1. Auth section: login, signup, forgot-password — all share a full-screen layout
  2. Main app: home feed, explore, profile — wrapped in bottom tab bar
  3. Settings section: account, notifications, privacy — grouped under /settings with a shared header

Design the route tree. Use pathless layouts and route groups appropriately. Then check your answer below.

Show solution
routes/ ├── __root.tsx ├── (auth)/ │ ├── (auth).login.tsx → /login │ ├── (auth).signup.tsx → /signup │ └── (auth).forgot-password.tsx → /forgot-password ├── _app.tsx → pathless layout for bottom tabs │ ├── _app.index.tsx → / │ ├── _app.explore.tsx → /explore │ └── _app.profile.tsx → /profile └── settings.tsx → /settings (layout) ├── settings.account.tsx → /settings/account ├── settings.notifications.tsx → /settings/notifications └── settings.privacy.tsx → /settings/privacy

Why this structure:

Quick Quiz

1. What does _admin.tsx do?

Adds /admin to the URL
Wraps children but doesn't add a URL segment
Hides all child routes from the router
The underscore prefix creates a pathless layout. Children render inside it, but the layout itself doesn't add a path segment.

2. When would you use a route group (marketing)?

When all marketing pages need a shared header component
When you want to organize marketing-related files in a folder without shared UI
When marketing pages should only load after user logs in
Route groups are purely organizational. If you need shared UI or logic, use a pathless layout instead.

3. Which URL matches routes/(public).about.tsx?

/(public)/about
/about
/public/about
Route groups don't affect URLs. The parentheses are ignored when building the path.
← Lesson 1: Route Tree Mental Model Lesson 3: Dynamic Routes & Splats →
🎓 Stuck on something?
Ask your teacher anything — when to use pathless layouts vs route groups, how to refactor an existing route tree, or how this applies to your specific app structure.