Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Next.js Parallel Routes and Intercepting Routes: Slot Layouts and Modals

Named slots render several pages in one layout, and (.) interception makes a click open over the page while a direct link renders the full route. Why every slot needs default.tsx.

~5 min readNext.js
#Next.js#App Router#Routing#React
3D illustration of parallel route slots rendering beside a page with a modal card sliding over it

Quick Summary

Parallel routes and intercepting routes solve two different problems that are usually confused because they appear in the same example. A parallel route renders several pages simultaneously in one layout through named slots (@team, @analytics); an intercepting route ((.), (..), (...)) renders the same route file from a different URL context, which is what makes a deep link and a soft navigation show different UI for one address.

The modal pattern is the intersection: a @modal slot renders a photo detail, and (.)photo/[id] intercepts the click on a card so the URL updates to /photo/123 while the grid stays mounted behind it. Hard-loading /photo/123 renders the full page instead, because interception only applies to client-side navigation.

Every slot needs a default.tsx (or default.js). Without it, a hard navigation to a URL where a slot has no matching segment renders a 404 for the whole page — the single most common reason a working parallel-route setup breaks after a refresh or a direct link.

Basic Syntax & Core Signatures

tsx
// app/layout.tsx — slots arrive as props named after the folder, without the @ export default function RootLayout({ children, team, analytics, }: { children: React.ReactNode; team: React.ReactNode; analytics: React.ReactNode; }) { return ( <div className="shell"> <main>{children}</main> <aside>{team}</aside> <section>{analytics}</section> </div> ); }
code
app/ layout.tsx → receives children, team, analytics page.tsx → children @team/ default.tsx → rendered when no team segment matches page.tsx → / (soft) and any URL without a team match settings/page.tsx → /settings @analytics/ default.tsx page.tsx photo/ [id]/page.tsx → full page, used on hard navigation @modal/ default.tsx (.)photo/[id]/page.tsx → intercepts /photo/123 on soft navigation

An intercepting segment is a folder whose name starts with a parent marker, and the segment after the marker is the real route it intercepts:

FolderMeaning
(.)photo/[id]Intercept a segment one level below the current level, same URL path
(..)photo/[id]Intercept one level above the current level
(..)(..)photo/[id]Two levels above
(...)photo/[id]Intercept from the root of app

Slot props are typed React.ReactNode and are already rendered server output; you cannot call hooks on them, read from them, or pass data through. To have the layout know whether a slot is "open", read usePathname() in a small client component or pass params down from the page itself.

tsx
// app/@modal/default.tsx — renders nothing when no modal route is active export default function Default() { return null; } // app/@modal/(.)photo/[id]/page.tsx import { notFound } from "next/navigation"; import { getPhoto } from "@/lib/photos"; import { Modal } from "@/components/modal"; export default async function PhotoModal({ params, }: { params: Promise<{ id: string }>; }) { const { id } = await params; const photo = await getPhoto(id); if (!photo) notFound(); return ( <Modal> <img src={photo.src} alt={photo.alt} /> </Modal> ); }

The slide-over still has to be openable by keyboard and closable by Escape, and closing must move history back rather than push a new entry. router.back() is correct when the modal was reached from the grid; guard it, because a deep link opened in a new tab has no previous entry inside the app.

Key Comparison Table

MechanismChanges the URLRenders on hard loadState of other slotsPrimary use
Parallel slot (@x)NoYes, if the route matchesPreserved independentlyDashboards, split views, independent streaming
Intercepting routeYes (soft nav)Renders the real pagePreserved, parent stays mountedModals, quick previews, lightboxes
Nested layoutYesYesRemounted on segment changeShared chrome for a section
Route group (marketing)NoYesn/aLayout organisation without a URL segment
Client modal + local stateNoNoPreservedPurely local UI with no shareable URL

Practical Edge Cases & Deep Dives

1. default.tsx is not optional

If @analytics has only settings/page.tsx and no default.tsx, then / renders the layout with analytics unmatched. With soft navigation Next.js keeps the last-known slot content; on a hard load it has nothing to render and the request 404s. The fix is a one-line default.tsx per slot, and the habit of adding it the moment a slot folder is created.

tsx
// app/@analytics/default.tsx export default function Default() { return <p className="muted">Select a report</p>; }

To make the fallback match the slot's normal page, call the shared component with default props rather than duplicating markup — duplicated markup is what drifts after a redesign.

2. Closing a modal without losing the grid

Interception does not give you a close handler. The usual implementation is a client component that calls router.back() and falls back to pushing the parent route:

tsx
"use client"; import { useRouter, usePathname } from "next/navigation"; export function Modal({ children }: { children: React.ReactNode }) { const router = useRouter(); const pathname = usePathname(); function close() { if (window.history.length > 1) router.back(); else router.replace(pathname.split("/").slice(0, -1).join("/") || "/"); } return ( <div role="dialog" aria-modal="true" onKeyDown={(e) => e.key === "Escape" && close()}> <button onClick={close} aria-label="Close">×</button> {children} </div> ); }

history.length is not a reliable proof that the previous entry is in your app (a fresh tab after a redirect still reports 2). For production, mark the navigation yourself: set window.history.state.__modal = true before pushing, and check that flag instead.

A link to /photo/123 opened in a new tab renders app/photo/[id]/page.tsx — the non-intercepted route. That is the point, but it means the two files must share their detail component, or the preview and the page will differ in content and in metadata. Metadata also comes from the real page: generateMetadata in the intercepted file is used only while the modal is rendered, and the document title on hard load comes from the non-intercepted route.

tsx
// both files render the same component export default async function PhotoPage({ params }: { params: Promise<{ id: string }> }) { const { id } = await params; return <PhotoDetail id={id} />; }

4. Auth-conditional slots and null

A slot can render nothing for anonymous users by returning null from the slot's page.tsx. This is a rendering decision, not an authorisation one: the segment still resolves and its page.tsx still runs, so data must still be protected where it is read. Combine with notFound() for hidden resources rather than relying on a null slot.

tsx
// app/@team/page.tsx import { getSession } from "@/lib/session"; export default async function TeamPanel() { const session = await getSession(); if (!session) return null; // hides chrome, not data return <TeamList orgId={session.orgId} />; }

5. Prefetching across an interception boundary

<Link href="/photo/123"> inside the grid prefetches the intercepted variant when the router knows the current layout is intercepting, so the modal opens without a network round trip on hover. The catch: prefetch is skipped when the link is rendered in a component that is not a client component boundary with prefetch default, and disabled entirely with prefetch={false}. If a modal feels slow only the first time, check that the grid row is not re-rendered into a new React tree on every scroll — a remount discards the prefetched payload.

6. Nested slots and the children fallthrough

Slots compose: @modal can itself contain a nested layout with its own default.tsx. A common failure is nesting a slot under a dynamic segment so the slot exists only for some params; on URLs where the param is missing, the slot is unmatched and falls to default.tsx. If the slot's default.tsx returns null, the layout still reserves its grid area, so use CSS (:empty, or a state class from usePathname) if an empty column must collapse rather than sit blank.

Common Runtime & Configuration Mistakes

SymptomCauseFix
404 on refresh at a URL that worked by clickMissing default.tsx in a slotAdd default.tsx returning null or the fallback UI
Modal renders twice (once behind, once over)Intercepting file and real page both rendered by a shared layoutIntercept at the slot level only, keep the real page outside the slot
Close button navigates forward instead of backrouter.push used in close handlerUse router.back(), guard with your own history flag
Modal never appears on clickInterception folder placed at the wrong depth ((.) vs (..))Match the marker to the relationship between the current segment and the target
Slot content stale after logoutSlot cached by client router cacherouter.refresh() after mutation, or revalidatePath on the server
Type error: slot not assignable to ReactNodeSlot typed with a prop shapeDeclare slot props as React.ReactNode in the layout signature

Try matching browser tools

All tools

Small utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Next.js guides

More in Next.js

All Next.js guides

The guides filed next to this one in Next.js, in library order.