DEV Community

Cover image for Parallel Routes in Next.js App Router — Rendering Multiple Pages in One Layout
Aon infotech
Aon infotech

Posted on

Parallel Routes in Next.js App Router — Rendering Multiple Pages in One Layout

#ai #webdev #nextjs #react

Parallel Routes let you render multiple pages simultaneously within the same layout. Instead of navigating away from a page to show another one, you can display both at the same time — a dashboard with independently navigable sections, a main content area alongside a sidebar that changes with its own navigation, or a feed with an openable detail panel that doesn't replace the feed.

This is one of the more powerful App Router features and one of the more confusing to set up initially. Here's the complete pattern, including the design approach used for complex multi-panel interfaces like the generation tool at Pixova.

The Core Concept — Named Slots

Parallel routes use named slots: special folders prefixed with @ that define independent rendering areas within a layout.

app/
├── layout.tsx              ← Receives slot props
├── page.tsx                ← Default slot content
├── @sidebar/
│   ├── page.tsx            ← Sidebar default
│   └── settings/
│       └── page.tsx        ← Sidebar settings view
└── @modal/
    ├── page.tsx            ← Modal default (null)
    └── photo/[id]/
        └── page.tsx        ← Photo modal
Enter fullscreen mode Exit fullscreen mode

The layout receives each slot as a prop:

// app/layout.tsx
export default function Layout({
  children,
  sidebar,
  modal,
}: {
  children: React.ReactNode;
  sidebar: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
    <div className="flex h-screen">
      <aside className="w-64 border-r">{sidebar}</aside>
      <main className="flex-1">{children}</main>
      {modal}
    </div>
  );
}
Enter fullscreen mode Exit fullscreen mode

Now children, sidebar, and modal can each navigate independently.

Independent Navigation — The Key Behavior

Each parallel route slot navigates independently. When a user navigates from / to /settings, the children slot updates. The sidebar slot stays exactly where it was — its navigation state is independent.

This is the key difference from nested layouts. Nested layouts rerender from the changed segment outward. Parallel routes don't affect each other.

User is at / (children shows home, sidebar shows default nav)
User navigates to /settings
→ children now shows settings
→ sidebar unchanged, still shows default nav

User then clicks "Account" in sidebar
→ sidebar now shows account content
→ children unchanged, still shows settings
Enter fullscreen mode Exit fullscreen mode

Default Files — Handling Missing States

When a route navigates and a parallel slot doesn't have content for that URL, Next.js needs to know what to show. This is where default.tsx comes in:

app/
├── @sidebar/
│   ├── default.tsx   ← Shown when sidebar has no matching route
│   └── filters/
│       └── page.tsx
└── @modal/
    └── default.tsx   ← Usually null — modal is hidden by default
Enter fullscreen mode Exit fullscreen mode 
// app/@modal/default.tsx
// Return null when no modal should be shown
export default function ModalDefault() {
  return null;
}

// app/@sidebar/default.tsx
// Sidebar shows its default nav when no specific route is active
export default function SidebarDefault() {
  return <DefaultNavigation />;
}
Enter fullscreen mode Exit fullscreen mode

Without default.tsx, navigating to a URL that doesn't match a slot will cause a 404 or error.

Modal Pattern — The Killer Use Case

The most compelling use of parallel routes: opening a detail modal without losing the underlying page, then being able to close the modal and return to the page — with full URL sharing support.

app/
├── @modal/
│   ├── default.tsx         ← null (no modal)
│   └── photos/
│       └── [id]/
│           └── page.tsx    ← Photo detail modal
├── layout.tsx
└── photos/
    └── page.tsx            ← Photo grid
Enter fullscreen mode Exit fullscreen mode

When a user navigates to /photos/123, the @modal slot renders the photo detail while the photo grid stays visible underneath:

// app/@modal/photos/[id]/page.tsx
'use client';
import { useRouter } from 'next/navigation';

export default function PhotoModal({ params }: { params: { id: string } }) {
  const router = useRouter();

  return (
    <div 
      className="fixed inset-0 bg-black/60 flex items-center justify-center z-50"
      onClick={() => router.back()}
    >
      <div 
        className="bg-white rounded-xl max-w-2xl w-full mx-4 p-6"
        onClick={e => e.stopPropagation()}
      >
        <PhotoDetail id={params.id} />
      </div>
    </div>
  );
}
Enter fullscreen mode Exit fullscreen mode 
// app/@modal/default.tsx
export default function ModalDefault() {
  return null; // No modal rendered
}
Enter fullscreen mode Exit fullscreen mode

The URL /photos/123 can be shared and when followed directly, the photo modal renders. When navigated to from within the app, the grid stays visible underneath. router.back() closes the modal and returns to the photo grid.

Intercepting Routes — Paired with Parallel Routes

Intercepting routes extend the modal pattern: intercept a link that would normally navigate away and instead show the content in a modal.

app/
├── photos/
│   ├── page.tsx           ← Photo grid
│   └── [id]/
│       └── page.tsx       ← Photo page (for direct access)
└── @modal/
    ├── default.tsx        ← null
    └── (.)photos/         ← Intercepts /photos/:id when navigating from same level
        └── [id]/
            └── page.tsx   ← Photo in modal
Enter fullscreen mode Exit fullscreen mode

The (.) syntax intercepts routes at the same level. (..) intercepts one level up. (...) intercepts from root.

When a user clicks a photo link from the grid, (.)photos/[id] intercepts and shows the modal. When they refresh or share the URL /photos/123, Next.js serves photos/[id]/page.tsx — the full page version.

When to Use Parallel Routes

Use parallel routes for:

  • Dashboard layouts where sidebar and main content navigate independently
  • Modal patterns where the underlying page should stay visible
  • Split-view UIs with two independently navigable panes
  • Tabs that change URL without replacing the surrounding layout

Don't use parallel routes for:

  • Simple conditional UI — use state or context instead
  • Content that appears based on user interaction without changing the URL — useState is simpler
  • Small nested components — regular component composition works fine

The file system complexity of parallel routes is only worth it when you genuinely need independent URL-based navigation in multiple slots simultaneously.

Loading and Error States Per Slot

Each parallel route slot can have its own loading and error states:

app/
├── @sidebar/
│   ├── loading.tsx    ← Sidebar loading skeleton
│   ├── error.tsx      ← Sidebar error state
│   └── page.tsx
└── @modal/
    ├── loading.tsx    ← Modal loading state
    └── ...
Enter fullscreen mode Exit fullscreen mode

This means the sidebar can show a skeleton while loading without affecting the main content area, and a sidebar error doesn't break the rest of the page.

// app/@sidebar/loading.tsx
export default function SidebarLoading() {
  return (
    <div className="p-4 space-y-3">
      {[...Array(5)].map((_, i) => (
        <div key={i} className="h-8 bg-neutral-100 rounded animate-pulse" />
      ))}
    </div>
  );
}
Enter fullscreen mode Exit fullscreen mode

Summary

Parallel routes use @named folders to define independent rendering slots in a layout. Each slot navigates independently — changes in one slot don't affect others.

The essential files: layout.tsx accepts slot props, default.tsx provides fallback content when a slot has no matching route, loading.tsx and error.tsx give per-slot loading and error states.

The modal pattern — pairing parallel routes with intercepting routes for URL-addressable modals that don't replace the underlying page — is the feature's most powerful application.

Debugging Common Issues

Slot showing wrong content after navigation: Check that default.tsx exists for each slot at every level where navigation could leave the slot without matching content.

404 when navigating parallel routes: Usually means a default.tsx is missing. Every @slot folder that could be in a "no matching route" state needs a default.tsx.

Slots affecting each other: Parallel route slots are independent — if a change in one is affecting another, check that the layout isn't rerendering more than expected. Use React DevTools to verify slot isolation.

Refresh shows different content than navigation: This is the intercepting route working correctly — direct access shows the full page, navigation within the app intercepts to show the modal. If you don't want this behavior, remove the intercept folder.

The File Structure at a Glance

For a dashboard with an independent sidebar and an optional modal:

app/
├── layout.tsx                    # children + sidebar + modal slots
├── page.tsx                      # Main content default
├── settings/
│   └── page.tsx                  # Main content: settings
├── @sidebar/
│   ├── default.tsx               # Default sidebar nav
│   ├── page.tsx                  # Sidebar: home
│   └── admin/
│       └── page.tsx              # Sidebar: admin nav
└── @modal/
    ├── default.tsx               # null — no modal
    └── (.)items/
        └── [id]/
            └── page.tsx          # Item detail modal
Enter fullscreen mode Exit fullscreen mode

That structure handles: independent sidebar navigation, optional modals that intercept item links, URL-addressable modal state, and per-slot loading/error states — all with clean URL semantics.

Top comments (0)