Intercepting routes and modals

One address, two ways to show it

In the tea shop's list of teas, a visitor often wants a quick look at one tea without leaving the list. The tea should still have an address of its own, like /teas/green, that the visitor can share, bookmark and reload. Intercepting routes give one address two pages: one for a client-side navigation from the right part of the app, like a click on the tea in the list, and one for every other way in.

A folder whose name starts with (.), (..) or (...) is an intercepting route. The rest of its name is another route, the one it intercepts, counted from where the folder sits. Here, app/teas/(.)[id] intercepts /teas/[id], the address of each tea ([id] is a dynamic segment). This shop is a real Next.js 16.4.3 project, built with next build, run with next start, and clicked through in real Chrome. Its root layout shows a line, You are on /teas., from a small Client Component, app/address.tsx, that reads the address with usePathname(), so each step shows where the visitor is.

1import { findTea, teas } from "@/app/_lib/teas";2 3export function generateStaticParams() {4  return teas.map((tea) => ({ id: tea.id }));5}6 7export default async function QuickLook({ params }: { params: Promise<{ id: string }> }) {8  const { id } = await params;9  const tea = findTea(id);10  return (11    <main>12      <p>Quick look: {tea?.name}, ${tea?.price} a box</p>13    </main>14  );15}

The file shown first is app/teas/(.)[id]/page.tsx. Line 12 is the whole quick look: one line with the tea's name and price. Lines 3 to 5 list every tea's id for the build with generateStaticParams, as the real tea page does (generateStaticParams explains why a page that awaits params needs it, or a loading state, with Cache Components on). The real page is app/teas/[id]/page.tsx: the tea's name, its note, its price and a link back to the list. The Steps tab lists three steps:

• Step 1, open /teas: the page, then the router's prefetches, which ask early for the pages the links point to. Each one carries the header next-url: /teas: the router telling the server which address the visitor is on.
• Step 2, click Green tea: the address is /teas/green, and the page shows Quick look: Green tea, $4 a box. Whatever the router still needed for it, it asked for with the same next-url: /teas, or had already prefetched.
• Step 3, reload /teas/green: one document request, for a whole page, and the full tea page: Green tea, Fresh and grassy. Brew it for 3 minutes., $4 a box and All teas.

One address, two pages. A click on a Link is a soft navigation: Next.js's router changes the page in place, without loading a new HTML page; so is a call to router.push. Only a soft navigation can be intercepted, and only one that starts from the intercepting folder's route or below it: here, /teas. A reload, an address typed into the browser, or a link from another site is a hard navigation: the browser asks the server for a whole new page, and gets the real one. Here, the quick look took the list's place. A modal keeps the list and puts the tea on top of it, with one more folder: a slot, from Parallel routes.

(.), (..), (..)(..) and (...) count route segments

The marker at the start of the folder's name says where the intercepted route starts, like ./ and ../ in a file path:

• (.) starts at the same level as the folder's own route.
• (..) starts one level up.
• (..)(..) starts two levels up.
• (...) starts at the root of the app.

The levels are route segments: the parts of the address between slashes. Only folders that add a segment count. A slot like @modal adds none, and neither does a route group like (shop), from Route groups and private folders. So a folder inside app/teas/@modal counts from /teas, not from @modal. Here the shop's teas get a layout with a modal slot, and the cart opens in it:

1import Modal from "@/app/modal";2 3export default function CartModal() {4  return (5    <Modal title="Your cart">6      <p>2 boxes of Green tea</p>7    </Modal>8  );9}

Before you read on, pick each marker and look at step 4, a click on Cart from /teas. With (.)cart, the build passed and listed ○ /teas/(.)cart, but step 4 shows the full cart page: (.) counted from /teas, so the folder intercepts /teas/cart, an address no link goes to. With (..)cart and (...)cart, step 4 shows Your cart in the modal, on top of the list. (..)(..)cart would start above the root, and the build stops: Cannot use (..)(..) marker at the root level or one level up. Each row is one marker, in a folder inside app/teas/@modal:

Next.js's own error proves that slots don't count. Put the tea modal in app/@modal/(..)teas/[id], and the build stops with Invalid interception route: /(..)teas/[id]. Cannot use (..) marker at the root level, use (.) instead. The route it names has no @modal in it: Next.js dropped the slot, found the folder at the root, and saw nothing above it.

Steps 1 and 2 show the other half of the rule: where the visitor is. In every version, step 2 clicks Cart on /, and the full cart page shows, even with (..)cart. An intercepting route only catches clicks from the route its folder belongs to, or a route below it. That's what next-url is for: app/teas/@modal/(..)cart intercepts /cart only when next-url is /teas or starts with /teas/.

A modal: a slot, an interception and default.tsx

A modal is a box on top of the page that the visitor has to deal with, or close, before using the page behind it. With an address of its own, it's four files:

1. app/layout.tsx renders the slot: {modal} on line 15, after {children}.
2. app/@modal/default.tsx returns null. It's what the slot shows when none of its pages matches the address: on every page without a modal.
3. app/@modal/(.)teas/[id]/page.tsx is the tea, in a modal. @modal isn't a segment, so (.) is the root's level, and the folder intercepts /teas/[id].
4. app/teas/[id]/page.tsx is the tea's full page, for every other way in.

1import { notFound } from "next/navigation";2import Modal from "@/app/modal";3import { findTea, teas } from "@/app/_lib/teas";4 5export function generateStaticParams() {6  return teas.map((tea) => ({ id: tea.id }));7}8 9export default async function TeaModal({ params }: { params: Promise<{ id: string }> }) {10  const { id } = await params;11  const tea = findTea(id);12  if (!tea) notFound();13  return (14    <Modal title={tea.name}>15      <p>{tea.note}</p>16      <p>${tea.price} a box</p>17      <a href={`/teas/${tea.id}`}>Open the full page</a>18    </Modal>19  );20}

In the file shown first, line 14 wraps the tea in Modal, from app/modal.tsx, and line 17 is a plain <a> to the full page. The Steps tab opens on step 2, the click on Green tea. The address is /teas/green. The page still shows Our teas and both links, and after them the modal: Close, the heading Green tea, its note, its price and Open the full page. The intercepted answer had nothing new for children, so the router kept the list there, the way a slot keeps its page on a click.

The Terminal tab lists /(.)teas/[id] with ○ /(.)teas/green and ○ /(.)teas/mint, beside /teas/[id]: Next.js prerendered the modal's version of each tea as well as its full page. In the Network tab, /teas/green answered with Vary naming next-url. Vary tells caches that the answer depends on those request headers, so they keep the modal and the full page apart. /teas, which nothing intercepts, doesn't name it.

Next.js 16.4.3 checks that the full page is there. Take app/teas/[id]/page.tsx away, and the build stops:

1import { notFound } from "next/navigation";2import Modal from "@/app/modal";3import { findTea, teas } from "@/app/_lib/teas";4 5export function generateStaticParams() {6  return teas.map((tea) => ({ id: tea.id }));7}8 9export default async function TeaModal({ params }: { params: Promise<{ id: string }> }) {10  const { id } = await params;11  const tea = findTea(id);12  if (!tea) notFound();13  return (14    <Modal title={tea.name}>15      <p>{tea.note}</p>16      <p>${tea.price} a box</p>17      <a href={`/teas/${tea.id}`}>Open the full page</a>18    </Modal>19  );20}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...⚠ Strict route matching is enabled by default. This validation indicates a bug in your app's route structure, but you can temporarily restore loose route matching by setting `deprecated.looseRouteMatching` to `true` in your Next.js config. > Build error occurredError: Turbopack build failed with 1 error:./app/@modal/(.)teas/[id]/page.tsxError: Interception routes must have a canonical routeThe following interception routes do not have a canonical route:- /(.)teas/[id] (expected /teas/[id]) Every interception route must have a matching non-interception route so the URL can be loaded directly or refreshed.     at ignore-listed frames

The build says Interception routes must have a canonical route, and names it: /(.)teas/[id] (expected /teas/[id]). A canonical route is the ordinary page for the same address, the one a reload gets. Without it, a reload of /teas/green would have nothing to show. Next.js 16.4 added this check to its strict route matching, which Parallel routes met.

A click or a reload decides what shows

What shows depends on how the visitor arrived, not on the address. Each row is one thing the visitor did in the recorded steps of the modal above:

Steps 9 and 10 are two ways to the full page. Step 9 clicks Open the full page, the plain <a> on line 17. A plain link isn't handled by Next.js's router, so the browser loads a whole new page: the step made one document request, and a full page load is never intercepted. Step 10 reloads, with the same result. That's how a modal can offer its full page.

Step through both below. Before you start, guess which step decides between the modal and the full page:

In the click, step 4 decides. The address and next-url both match the intercepting route, so the server answers with the modal's page. In the reload, there's no next-url to read: a whole page is asked for by the browser, which knows nothing about where the visitor was. The recorded document requests carry none of the router's headers.

Closing the modal

The modal has its own address, so closing it means leaving that address, back to /teas. The recording closes it three ways:

• Escape, in step 3, and the Close button, in step 5. The button sits in a <form method="dialog">, on lines 16 to 18 of app/modal.tsx: a form that closes its dialog instead of sending anything. Both close the <dialog>, and line 15's onClose calls router.back().
• The browser's Back button, in step 7. The browser goes back on its own: the address is /teas, the modal is gone, and the address stayed /teas, one entry back, not two.

router.back() goes to the previous entry in the browser's history, like the Back button, as Linking and navigating showed. Closing the modal that way leaves the history as the visitor saw it: the list, then the tea they opened, and back. Next.js's docs also show closing with a Link to /teas; that's a new navigation, with a new history entry, and it needs the catch-all page further down.

router.back() assumes there's a page to go back to, inside the shop. The modal only exists after a client-side navigation from /teas or below, so for the modal that's always true. The full page is different: a visitor who opens a shared link arrives on it directly. Here the full page has a Back button that calls router.back(), and Chrome opened its address the way a shared link does:

1import BackButton from "@/app/back-button";2import { notFound } from "next/navigation";3import { findTea, teas } from "@/app/_lib/teas";4 5export function generateStaticParams() {6  return teas.map((tea) => ({ id: tea.id }));7}8 9export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {10  const { id } = await params;11  const tea = findTea(id);12  if (!tea) notFound();13  return (14    <main>15      <h1>{tea.name}</h1>16      <p>{tea.note}</p>17      <p>${tea.price} a box</p>18      <BackButton />19    </main>20  );21}

Step 2 clicked Back, and the visitor left the shop. The recording labels the address blank: that's Chrome's empty tab, about:blank, which was this window's previous page. For a real visitor, it's the chat app the link came from, or nothing at all in a new tab. So the full page links to the list with a Link, as line 18 of the real app/teas/[id]/page.tsx does, and only the modal uses router.back().

One more trap. Give the modal a link to another page, like Go to your cart, and click it. Guess first: does the modal close?

1import Link from "next/link";2import { notFound } from "next/navigation";3import Modal from "@/app/modal";4import { findTea, teas } from "@/app/_lib/teas";5 6export function generateStaticParams() {7  return teas.map((tea) => ({ id: tea.id }));8}9 10export default async function TeaModal({ params }: { params: Promise<{ id: string }> }) {11  const { id } = await params;12  const tea = findTea(id);13  if (!tea) notFound();14  return (15    <Modal title={tea.name}>16      <p>{tea.note}</p>17      <p>${tea.price} a box</p>18      <a href={`/teas/${tea.id}`}>Open the full page</a> <Link href="/cart">Go to your cart</Link>19    </Modal>20  );21}

With only default.tsx, the cart shows, and the modal stays open on top of it. It's the parallel routes rule again: on a client-side navigation, a slot with nothing for the new address keeps its last page. default.tsx only shows when no page in the slot matches the address. The fix is a page in the slot that matches the other addresses and shows nothing: app/@modal/[...rest]/page.tsx, a catch-all segment (Dynamic routes showed them) that returns null. It handles every address outside the modal that has at least one segment, like /cart, on a click and after a full page load alike. Keep default.tsx too: it's the fallback when no page in the slot matches, which here is mainly /, because [...rest] needs at least one segment.

A modal everyone can use

A modal blocks the page behind it, so people who use a keyboard or a screen reader need to know it's there and how to leave it. The HTML <dialog> element, opened with its showModal() method, does most of that for you. Here is app/modal.tsx again, with the steps that pressed Escape:

1"use client";2 3import { useEffect, useRef } from "react";4import { useRouter } from "next/navigation";5 6export default function Modal({ title, children }: { title: string; children: React.ReactNode }) {7  const router = useRouter();8  const dialog = useRef<HTMLDialogElement>(null);9 10  useEffect(() => {11    dialog.current?.showModal();12  }, []);13 14  return (15    <dialog ref={dialog} aria-labelledby="modal-title" onClose={() => router.back()}>16      <form method="dialog">17        <button>Close</button>18      </form>19      <h2 id="modal-title">{title}</h2>20      {children}21    </dialog>22  );23}

Line 8 makes a ref to the <dialog> element, and the Effect on lines 10 to 12 calls showModal() once the dialog is on the page. Line 15 names the dialog with aria-labelledby, which points at the heading on line 19, so screen readers can announce the dialog by its heading, like Green tea. Each row is one thing a modal needs: how <dialog> gives it, and where the recording shows it.

Steps 2, 4, 6 and 8 have the focus on Close, the first thing in the dialog you can focus. Steps 3 and 5 have it back on the Green tea link, so a keyboard user carries on from where they were (Keyboard and focus explains focus). The page behind being inert (it can't be clicked, and Tab skips it) comes from the HTML standard for showModal(); the recording doesn't show it.

A sign-in form in the same slot

One slot can hold many modals. The shop adds Sign in to its links. app/@modal/(.)sign-in/page.tsx shows the form in the same Modal, and app/sign-in/page.tsx is the full page. Both import one form, from app/sign-in/sign-in-form.tsx, so they never drift apart. The form is a stand-in: it doesn't sign anyone in. The Authentication lesson builds a real one. The slot also has the catch-all page.

1import Modal from "@/app/modal";2import SignInForm from "@/app/sign-in/sign-in-form";3 4export default function SignInModal() {5  return (6    <Modal title="Sign in">7      <SignInForm />8    </Modal>9  );10}

In the file shown first, lines 6 and 7 put the shared form inside Modal, with the heading Sign in. Step 2 clicks Sign in on the home page: the address is /sign-in, the home page is still there, and the form is in the modal, with focus on Close. (.)sign-in sits at the root's level, so it catches clicks from every page. Step 3 types asha@example.com into Email. Step 4 presses Escape: the address is / again, with focus back on the Sign in link. Step 5 reloads /sign-in, and gets the full page. The Terminal tab lists both ○ /(.)sign-in and ○ /sign-in.

Sort these visits: does the visitor get the modal, or the full page?

Common mix-ups

• "The markers count folders." No. They count route segments: slots and route groups don't count. (..) in app/@modal stopped the build.
• "An intercepted address always shows the modal." No. Only a client-side navigation from the folder's route or below does: Cart from / showed the full cart. A reload or a shared link showed the full page.
• "The modal's page is enough." No. Next.js 16.4.3 stops the build without the full page: Interception routes must have a canonical route.
• "default.tsx closes the modal when the visitor clicks away." No. On a click, a slot keeps its last page, so on a click to the cart the slot kept the modal open. A [...rest] page that returns null closes it.
• "A Back button with router.back() is fine on the full page." No. A visitor from a shared link has no page of yours to go back to: the recorded Back left the shop.
• "Any box on top of the page is a modal." No. A modal moves focus into itself, closes with Escape, and keeps the page behind out of reach. showModal() does all three.

Each row is one file of the modal: when it shows, and why it's there.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

app/
  @modal/
    (.)teas/
      [id]/
        page.tsx
    default.tsx
  _lib/
    teas.ts
  cart/
    page.tsx
  teas/
    [id]/
      page.tsx
    page.tsx
  address.tsx
  layout.tsx
  modal.tsx
  page.tsx

import Link from "next/link";
import { notFound } from "next/navigation";
import { findTea, teas } from "@/app/_lib/teas";

export function generateStaticParams() {
  return teas.map((tea) => ({ id: tea.id }));
}

export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {
  const { id } = await params;
  const tea = findTea(id);
  if (!tea) notFound();
  return (
    <main>
      <h1>{tea.name}</h1>
      <p>{tea.note}</p>
      <p>${tea.price} a box</p>
      <Link href="/teas">All teas</Link>
    </main>
  );
}

app/
  _lib/
    teas.ts
  cart/
    page.tsx
  teas/
    @modal/
      ????cart/
        page.tsx
      default.tsx
    [id]/
      page.tsx
    layout.tsx
    page.tsx
  address.tsx
  layout.tsx
  modal.tsx
  page.tsx

import Modal from "@/app/modal";

export default function CartModal() {
  return (
    <Modal title="Your cart">
      <p>2 boxes of Green tea</p>
    </Modal>
  );
}

app/
  @modal/
    (.)teas/
      [id]/
        page.tsx
  _lib/
    teas.ts
  cart/
    page.tsx
  teas/
    [id]/
      page.tsx
    page.tsx
  address.tsx
  layout.tsx
  modal.tsx
  page.tsx

export default function NoModal() {
  return null;
}

import Link from "next/link";
import { notFound } from "next/navigation";
import Modal from "@/app/modal";
import { findTea, teas } from "@/app/_lib/teas";

export function generateStaticParams() {
  return teas.map((tea) => ({ id: tea.id }));
}

export default async function TeaModal({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const tea = findTea(id);
  if (!tea) notFound();
  return (
    <Modal title={tea.name}>
      <p>{tea.note}</p>
      <p>${tea.price} a box</p>
      <a href={`/teas/${tea.id}`}>Open the full page</a> <Link href="/cart">Go to your cart</Link>
    </Modal>
  );
}

export default function NoModalHere() {
  return null;
}

import BackButton from "@/app/back-button";
import { notFound } from "next/navigation";
import { findTea, teas } from "@/app/_lib/teas";

export function generateStaticParams() {
  return teas.map((tea) => ({ id: tea.id }));
}

export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {
  const { id } = await params;
  const tea = findTea(id);
  if (!tea) notFound();
  return (
    <main>
      <h1>{tea.name}</h1>
      <p>{tea.note}</p>
      <p>${tea.price} a box</p>
      <BackButton />
    </main>
  );
}

import Link from "next/link";
import { notFound } from "next/navigation";
import { findTea, teas } from "@/app/_lib/teas";

export function generateStaticParams() {
  return teas.map((tea) => ({ id: tea.id }));
}

export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {
  const { id } = await params;
  const tea = findTea(id);
  if (!tea) notFound();
  return (
    <main>
      <h1>{tea.name}</h1>
      <p>{tea.note}</p>
      <p>${tea.price} a box</p>
      <Link href="/teas">All teas</Link>
    </main>
  );
}

Check your understanding

Key takeaways

• A folder starting with (.), (..), (..)(..) or (...) intercepts another route, counted in route segments. Slots and route groups don't count.
• Only a client-side navigation (a Link click or router.push) from the folder's route, or below it, is intercepted. The router says where the visitor is with next-url.
• A reload, a typed address or a shared link is a full page load, and shows the real page.
• A modal is a @modal slot, an intercepting route in it, a default.tsx that returns null, and the full page. Next.js 16.4 stops the build without the last two.
• Close the modal with router.back(), give the slot a catch-all page that returns null, and link the full page to the list with a Link.
• Use <dialog> with showModal() and aria-labelledby: focus moves in, Escape closes it, and focus comes back.

Coming next: proxy.ts. It runs code before a request reaches any route: rewrites, redirects, headers and cookies.