Interceptando Rotas

Q: O que significam as convenções de ponto (.), (..), (..)(..), e (...)?

(.) corresponde ao mesmo nível de rota (..) corresponde a um nível de rota acima (..)(..) corresponde a dois níveis de rota acima (...) corresponde a partir do nível raiz

Q: Por que default.tsx é necessário no slot @modal?

Sem default.tsx, navegar para fora da rota interceptada e depois de volta pode causar erros. Ele fornece um fallback (geralmente retornando null) quando nenhum modal está ativo.

Q: Como você fecha um modal interceptado?

Chame router.back() do hook useRouter. Como a interceptação usa navegação do lado do cliente, voltar restaura a visualização anterior.

Q: Como você digita os params em uma rota interceptada de Componente Cliente?

Use React.use() para desempacotar o Promise, pois você não pode usar await em Componentes Cliente.

Q: Armadilha: O que acontece com históricos de navegação complexos e múltiplos rotas interceptadas?

router.back() remove a última entrada do histórico, que pode ser outro modal em vez da página não modal. Usuários que navegam por várias rotas interceptadas podem precisar voltar várias vezes.

Intercepting routes permitem carregar uma rota dentro do layout atual durante a navegação do lado do cliente, preservando a página completa em acesso direto à URL ou atualização. O caso de uso clássico é um modal que abre inline, mas tem sua própria URL compartilhável.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

Convenção      Corresponde
(.)pasta       Mesmo nível (como ./pasta)
(..)pasta      Um nível acima (como ../pasta)
(..)(..)pasta  Dois níveis acima (como ../../pasta)
(...)pasta     Nível raiz (como /pasta de qualquer lugar)

app/
├── layout.tsx
├── @modal/
│   ├── default.tsx              # Renderiza nada quando nenhum modal está ativo
│   └── (.)photo/[id]/page.tsx   # Intercepta /photo/:id → renderiza no modal
├── photo/[id]/
│   └── page.tsx                 # Página completa para /photo/:id (acesso direto)
└── page.tsx                     # Página de galeria com miniaturas de fotos

Quando usar isso: Galerias de fotos com pré-visualizações em modal, modais de login com URLs /login, pré-visualizações de detalhes de itens em uma lista, ou qualquer padrão onde uma rota deve aparecer como um modal durante a navegação, mas como uma página completa em acesso direto.

Exemplo de Trabalho

// app/layout.tsx - Layout raiz com slot de modal
export default function RootLayout({
  children,
  modal,
}: {
  children: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        {modal}
      </body>
    </html>
  );
}

// app/@modal/default.tsx - Renderiza nada quando nenhum modal é interceptado
export default function ModalDefault() {
  return null;
}

// app/@modal/(.)photo/[id]/page.tsx - Rota interceptada (exibe como modal)
"use client";
 
import { useRouter } from "next/navigation";
 
export default function PhotoModal({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const router = useRouter();
  // Em um componente cliente, use React.use() para desempacotar os params
  const { id } = require("react").use(params);
 
  return (
    <div
      className="fixed inset-0 z-50 flex items-center justify-center bg-black/60"
      onClick={() => router.back()}
    >
      <div
        className="relative max-h-[90vh] max-w-3xl overflow-hidden rounded-lg bg-white p-4"
        onClick={(e) => e.stopPropagation()}
      >
        <button
          onClick={() => router.back()}
          className="absolute right-2 top-2 text-gray-500 hover:text-gray-800"
        >
          Fechar
        </button>
        <img
          src={`/photos/${id}.jpg`}
          alt={`Foto ${id}`}
          className="max-h-[80vh] w-auto"
        />
        <p className="mt-2 text-center text-sm text-gray-600">Foto #{id}</p>
      </div>
    </div>
  );
}

// app/photo/[id]/page.tsx - Página completa (acesso direto à URL ou atualização)
export default async function PhotoPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
 
  return (
    <div className="flex min-h-screen flex-col items-center justify-center p-8">
      <img
        src={`/photos/${id}.jpg`}
        alt={`Foto ${id}`}
        className="max-h-[80vh] rounded-lg"
      />
      <h1 className="mt-4 text-2xl font-bold">Foto #{id}</h1>
      <a href="/" className="mt-4 text-blue-600 hover:underline">
        Voltar para a galeria
      </a>
    </div>
  );
}

// app/page.tsx - Página de galeria com links que disparam a interceptação
import Link from "next/link";
 
const photos = Array.from({ length: 12 }, (_, i) => ({
  id: String(i + 1),
  title: `Foto ${i + 1}`,
}));
 
export default function GalleryPage() {
  return (
    <div className="p-8">
      <h1 className="mb-6 text-3xl font-bold">Galeria de Fotos</h1>
      <div className="grid grid-cols-3 gap-4">
        {photos.map((photo) => (
          <Link key={photo.id} href={`/photo/${photo.id}`}>
            <img
              src={`/photos/${photo.id}.jpg`}
              alt={photo.title}
              className="aspect-square rounded-lg object-cover hover:opacity-80"
            />
          </Link>
        ))}
      </div>
    </div>
  );
}

Mergulho Profundo

Como Funciona

A interceptação ocorre apenas na navegação do lado do cliente. Quando um usuário clica em um <Link>, o Next.js renderiza a rota interceptadora em vez da rota de destino.
Acesso direto à URL ou atualização ignora a interceptação. Digitar a URL ou atualizar carrega a versão completa da página em app/photo/[id]/page.tsx.
Rotas interceptadoras usam slots de rotas paralelas. A pasta @modal é uma rota paralela. A rota interceptadora (.)photo/[id] é colocada dentro dela.
A convenção de ponto indica a profundidade relativa. (.) significa o mesmo nível, (..) significa um nível acima. Isso é relativo ao segmento da rota, não ao sistema de arquivos.
default.tsx é necessário no slot. Sem ele, o slot renderiza nada em rotas não interceptadas, e o Next.js pode gerar erros na navegação direta.
router.back() fecha o modal. Como a interceptação usa navegação do lado do cliente, voltar restaura a visualização anterior.
A página completa ainda existe em sua URL. A interceptação não remove a rota original - ela a sombreia apenas durante a navegação suave.

Variações

# Modal de login interceptado de qualquer página
app/
├── layout.tsx              # Inclui o slot @modal
├── @modal/
│   ├── default.tsx
│   └── (...)login/page.tsx # Intercepta /login do nível raiz
├── login/
│   └── page.tsx            # Página de login completa (acesso direto)
└── page.tsx

// app/@modal/(...)login/page.tsx - Modal de login
"use client";
 
import { useRouter } from "next/navigation";
 
export default function LoginModal() {
  const router = useRouter();
 
  return (
    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
      <div className="w-full max-w-md rounded-lg bg-white p-8">
        <h2 className="text-xl font-bold">Entrar</h2>
        <form className="mt-4 space-y-4">
          <input type="email" placeholder="Email" className="w-full rounded border p-2" />
          <input type="password" placeholder="Senha" className="w-full rounded border p-2" />
          <button type="submit" className="w-full rounded bg-blue-600 py-2 text-white">
            Entrar
          </button>
        </form>
        <button onClick={() => router.back()} className="mt-4 text-sm text-gray-500">
          Cancelar
        </button>
      </div>
    </div>
  );
}

# Interceptação aninhada - detalhe do item em uma lista
app/
├── feed/
│   ├── layout.tsx
│   ├── @detail/
│   │   ├── default.tsx
│   │   └── (..)post/[id]/page.tsx  # Intercepta /post/:id
│   └── page.tsx                     # Lista do feed
├── post/[id]/
│   └── page.tsx                     # Página completa do post

Notas TypeScript

// Páginas de rota interceptadoras têm as mesmas props que páginas regulares
interface InterceptedPageProps {
  params: Promise<{ id: string }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
}
 
// Layout que recebe um slot de rota paralela
interface LayoutWithModalProps {
  children: React.ReactNode;
  modal: React.ReactNode; // O slot @modal
}

Armadilhas

A convenção de ponto se refere a segmentos de rota, não a diretórios do sistema de arquivos. (..) sobe um segmento de rota, o que pode não corresponder a um nível de diretório se grupos de rotas estiverem envolvidos.
default.tsx deve existir no slot. Sem ele, navegar para fora da rota interceptada e depois de volta pode causar erros.
Atualizar a página carrega a rota completa, não a interceptada. Usuários que compartilham a URL verão a página completa, não o modal - isso é intencional.
Grupos de rotas (group) contam como um segmento para a convenção de ponto. Se sua rota interceptadora estiver dentro de um grupo de rotas, você pode precisar de um nível (..) extra.
A navegação de volta pode não funcionar como esperado com históricos complexos. Se o usuário navegou por várias rotas interceptadas, router.back() remove a última entrada, que pode ser outro modal.
Rotas interceptadoras adicionam complexidade. Se você não precisa do comportamento de URL compartilhável como página completa, um estado de modal simples do lado do cliente é mais fácil.
Slots de rotas paralelas devem ser filhos diretos de um layout. Você não pode aninhar @modal arbitrariamente - ele deve ser um irmão do layout que o renderiza.

Alternativas

Abordagem	Quando Usar
Estado de modal do lado do cliente	Modais simples sem URLs compartilháveis
Modal com parâmetro de consulta (`?modal=photo&id=1`)	Estado compartilhável sem a complexidade da interceptação de rotas
Rotas Paralelas sem interceptação	Visualizações lado a lado que não são modais
Elemento `dialog` com `useSearchParams`	Modais leves controlados por parâmetros de busca na URL

FAQs

Quando a interceptação de rotas acontece e quando não acontece?

A interceptação ocorre apenas durante a navegação do lado do cliente (clicando em um <Link>)
Acesso direto à URL, atualização da página ou links compartilhados ignoram a interceptação e carregam a versão completa da página

O que significam as convenções de ponto (.), (..), (..)(..), e (...)?

(.) corresponde ao mesmo nível de rota
(..) corresponde a um nível de rota acima
(..)(..) corresponde a dois níveis de rota acima
(...) corresponde a partir do nível raiz

Por que default.tsx é necessário no slot @modal?

Sem default.tsx, navegar para fora da rota interceptada e depois de volta pode causar erros. Ele fornece um fallback (geralmente retornando null) quando nenhum modal está ativo.

Como você fecha um modal interceptado?

Chame router.back() do hook useRouter. Como a interceptação usa navegação do lado do cliente, voltar restaura a visualização anterior.

"use client";
import { useRouter } from "next/navigation";
const router = useRouter();
// No botão de fechar:
<button onClick={() => router.back()}>Fechar</button>

Armadilha: As convenções de ponto se referem a diretórios do sistema de arquivos ou segmentos de rota?

Segmentos de rota, não diretórios do sistema de arquivos. Essa distinção é importante quando grupos de rotas estão envolvidos, pois os grupos de rotas (group) contam como um segmento para a convenção de ponto e podem exigir um nível (..) extra.

A rota interceptadora substitui a rota original?

Não. A página completa original ainda existe em sua URL. A interceptação apenas a sombreia durante a navegação suave (do lado do cliente). A original é renderizada no acesso direto ou atualização.

Qual é a relação entre rotas interceptadoras e rotas paralelas?

Rotas interceptadoras são colocadas dentro de slots de rotas paralelas (por exemplo, @modal). O slot é renderizado como uma prop no layout pai ao lado de children, permitindo que o modal e a página sejam exibidos simultaneamente.

Quais são os tipos TypeScript para uma página de rota interceptada?

interface InterceptedPageProps {
  params: Promise<{ id: string }>;
  searchParams: Promise<{
    [key: string]: string | string[] | undefined;
  }>;
}
 
interface LayoutWithModalProps {
  children: React.ReactNode;
  modal: React.ReactNode;
}

Como você digita os params em uma rota interceptada de Componente Cliente?

Use React.use() para desempacotar o Promise, pois você não pode usar await em Componentes Cliente.

"use client";
import { use } from "react";
 
export default function Modal({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = use(params);
  return <div>Item {id}</div>;
}

Armadilha: O que acontece com históricos de navegação complexos e múltiplos rotas interceptadas?

router.back() remove a última entrada do histórico, que pode ser outro modal em vez da página não modal. Usuários que navegam por várias rotas interceptadas podem precisar voltar várias vezes.

Quando você deve usar um modal simples do lado do cliente em vez de interceptar rotas?

Quando você não precisa de uma URL compartilhável para o conteúdo do modal. Rotas interceptadoras adicionam complexidade ao sistema de arquivos. Se o modal não precisa de sua própria URL ou fallback de página completa, o estado do lado do cliente é mais simples.

O @modal pode ser aninhado dentro de outro @slot?

Não. Slots de rotas paralelas devem ser filhos diretos de um diretório de layout. Você não pode aninhar @modal dentro de outro slot.

Relacionados

Rotas Paralelas - segmentos @slot que habilitam a interceptação
Navegação - useRouter para fechar modais
Rotas Dinâmicas - segmentos parametrizados em rotas interceptadas
Noções Básicas do App Router - visão geral das convenções de arquivo

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

Convenção      Corresponde
(.)pasta       Mesmo nível (como ./pasta)
(..)pasta      Um nível acima (como ../pasta)
(..)(..)pasta  Dois níveis acima (como ../../pasta)
(...)pasta     Nível raiz (como /pasta de qualquer lugar)

app/
├── layout.tsx
├── @modal/
│   ├── default.tsx              # Renderiza nada quando nenhum modal está ativo
│   └── (.)photo/[id]/page.tsx   # Intercepta /photo/:id → renderiza no modal
├── photo/[id]/
│   └── page.tsx                 # Página completa para /photo/:id (acesso direto)
└── page.tsx                     # Página de galeria com miniaturas de fotos

Exemplo de Trabalho

// app/layout.tsx - Layout raiz com slot de modal
export default function RootLayout({
  children,
  modal,
}: {
  children: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        {modal}
      </body>
    </html>
  );
}

// app/@modal/default.tsx - Renderiza nada quando nenhum modal é interceptado
export default function ModalDefault() {
  return null;
}

// app/@modal/(.)photo/[id]/page.tsx - Rota interceptada (exibe como modal)
"use client";
 
import { useRouter } from "next/navigation";
 
export default function PhotoModal({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const router = useRouter();
  // Em um componente cliente, use React.use() para desempacotar os params
  const { id } = require("react").use(params);
 
  return (
    <div
      className="fixed inset-0 z-50 flex items-center justify-center bg-black/60"
      onClick={() => router.back()}
    >
      <div
        className="relative max-h-[90vh] max-w-3xl overflow-hidden rounded-lg bg-white p-4"
        onClick={(e) => e.stopPropagation()}
      >
        <button
          onClick={() => router.back()}
          className="absolute right-2 top-2 text-gray-500 hover:text-gray-800"
        >
          Fechar
        </button>
        <img
          src={`/photos/${id}.jpg`}
          alt={`Foto ${id}`}
          className="max-h-[80vh] w-auto"
        />
        <p className="mt-2 text-center text-sm text-gray-600">Foto #{id}</p>
      </div>
    </div>
  );
}

// app/photo/[id]/page.tsx - Página completa (acesso direto à URL ou atualização)
export default async function PhotoPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
 
  return (
    <div className="flex min-h-screen flex-col items-center justify-center p-8">
      <img
        src={`/photos/${id}.jpg`}
        alt={`Foto ${id}`}
        className="max-h-[80vh] rounded-lg"
      />
      <h1 className="mt-4 text-2xl font-bold">Foto #{id}</h1>
      <a href="/" className="mt-4 text-blue-600 hover:underline">
        Voltar para a galeria
      </a>
    </div>
  );
}

// app/page.tsx - Página de galeria com links que disparam a interceptação
import Link from "next/link";
 
const photos = Array.from({ length: 12 }, (_, i) => ({
  id: String(i + 1),
  title: `Foto ${i + 1}`,
}));
 
export default function GalleryPage() {
  return (
    <div className="p-8">
      <h1 className="mb-6 text-3xl font-bold">Galeria de Fotos</h1>
      <div className="grid grid-cols-3 gap-4">
        {photos.map((photo) => (
          <Link key={photo.id} href={`/photo/${photo.id}`}>
            <img
              src={`/photos/${photo.id}.jpg`}
              alt={photo.title}
              className="aspect-square rounded-lg object-cover hover:opacity-80"
            />
          </Link>
        ))}
      </div>
    </div>
  );
}

Mergulho Profundo

Como Funciona

A interceptação ocorre apenas na navegação do lado do cliente. Quando um usuário clica em um <Link>, o Next.js renderiza a rota interceptadora em vez da rota de destino.
Acesso direto à URL ou atualização ignora a interceptação. Digitar a URL ou atualizar carrega a versão completa da página em app/photo/[id]/page.tsx.
Rotas interceptadoras usam slots de rotas paralelas. A pasta @modal é uma rota paralela. A rota interceptadora (.)photo/[id] é colocada dentro dela.
A convenção de ponto indica a profundidade relativa. (.) significa o mesmo nível, (..) significa um nível acima. Isso é relativo ao segmento da rota, não ao sistema de arquivos.
default.tsx é necessário no slot. Sem ele, o slot renderiza nada em rotas não interceptadas, e o Next.js pode gerar erros na navegação direta.
router.back() fecha o modal. Como a interceptação usa navegação do lado do cliente, voltar restaura a visualização anterior.
A página completa ainda existe em sua URL. A interceptação não remove a rota original - ela a sombreia apenas durante a navegação suave.

Variações

# Modal de login interceptado de qualquer página
app/
├── layout.tsx              # Inclui o slot @modal
├── @modal/
│   ├── default.tsx
│   └── (...)login/page.tsx # Intercepta /login do nível raiz
├── login/
│   └── page.tsx            # Página de login completa (acesso direto)
└── page.tsx

// app/@modal/(...)login/page.tsx - Modal de login
"use client";
 
import { useRouter } from "next/navigation";
 
export default function LoginModal() {
  const router = useRouter();
 
  return (
    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
      <div className="w-full max-w-md rounded-lg bg-white p-8">
        <h2 className="text-xl font-bold">Entrar</h2>
        <form className="mt-4 space-y-4">
          <input type="email" placeholder="Email" className="w-full rounded border p-2" />
          <input type="password" placeholder="Senha" className="w-full rounded border p-2" />
          <button type="submit" className="w-full rounded bg-blue-600 py-2 text-white">
            Entrar
          </button>
        </form>
        <button onClick={() => router.back()} className="mt-4 text-sm text-gray-500">
          Cancelar
        </button>
      </div>
    </div>
  );
}

# Interceptação aninhada - detalhe do item em uma lista
app/
├── feed/
│   ├── layout.tsx
│   ├── @detail/
│   │   ├── default.tsx
│   │   └── (..)post/[id]/page.tsx  # Intercepta /post/:id
│   └── page.tsx                     # Lista do feed
├── post/[id]/
│   └── page.tsx                     # Página completa do post

Notas TypeScript

// Páginas de rota interceptadoras têm as mesmas props que páginas regulares
interface InterceptedPageProps {
  params: Promise<{ id: string }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
}
 
// Layout que recebe um slot de rota paralela
interface LayoutWithModalProps {
  children: React.ReactNode;
  modal: React.ReactNode; // O slot @modal
}

Armadilhas

A convenção de ponto se refere a segmentos de rota, não a diretórios do sistema de arquivos. (..) sobe um segmento de rota, o que pode não corresponder a um nível de diretório se grupos de rotas estiverem envolvidos.
default.tsx deve existir no slot. Sem ele, navegar para fora da rota interceptada e depois de volta pode causar erros.
Atualizar a página carrega a rota completa, não a interceptada. Usuários que compartilham a URL verão a página completa, não o modal - isso é intencional.
Grupos de rotas (group) contam como um segmento para a convenção de ponto. Se sua rota interceptadora estiver dentro de um grupo de rotas, você pode precisar de um nível (..) extra.
A navegação de volta pode não funcionar como esperado com históricos complexos. Se o usuário navegou por várias rotas interceptadas, router.back() remove a última entrada, que pode ser outro modal.
Rotas interceptadoras adicionam complexidade. Se você não precisa do comportamento de URL compartilhável como página completa, um estado de modal simples do lado do cliente é mais fácil.
Slots de rotas paralelas devem ser filhos diretos de um layout. Você não pode aninhar @modal arbitrariamente - ele deve ser um irmão do layout que o renderiza.

Alternativas

Abordagem	Quando Usar
Estado de modal do lado do cliente	Modais simples sem URLs compartilháveis
Modal com parâmetro de consulta (`?modal=photo&id=1`)	Estado compartilhável sem a complexidade da interceptação de rotas
Rotas Paralelas sem interceptação	Visualizações lado a lado que não são modais
Elemento `dialog` com `useSearchParams`	Modais leves controlados por parâmetros de busca na URL

FAQs

Quando a interceptação de rotas acontece e quando não acontece?

A interceptação ocorre apenas durante a navegação do lado do cliente (clicando em um <Link>)
Acesso direto à URL, atualização da página ou links compartilhados ignoram a interceptação e carregam a versão completa da página

O que significam as convenções de ponto (.), (..), (..)(..), e (...)?

(.) corresponde ao mesmo nível de rota
(..) corresponde a um nível de rota acima
(..)(..) corresponde a dois níveis de rota acima
(...) corresponde a partir do nível raiz

Por que default.tsx é necessário no slot @modal?

Sem default.tsx, navegar para fora da rota interceptada e depois de volta pode causar erros. Ele fornece um fallback (geralmente retornando null) quando nenhum modal está ativo.

Como você fecha um modal interceptado?

Chame router.back() do hook useRouter. Como a interceptação usa navegação do lado do cliente, voltar restaura a visualização anterior.

"use client";
import { useRouter } from "next/navigation";
const router = useRouter();
// No botão de fechar:
<button onClick={() => router.back()}>Fechar</button>

Armadilha: As convenções de ponto se referem a diretórios do sistema de arquivos ou segmentos de rota?

A rota interceptadora substitui a rota original?

Qual é a relação entre rotas interceptadoras e rotas paralelas?

Quais são os tipos TypeScript para uma página de rota interceptada?

interface InterceptedPageProps {
  params: Promise<{ id: string }>;
  searchParams: Promise<{
    [key: string]: string | string[] | undefined;
  }>;
}
 
interface LayoutWithModalProps {
  children: React.ReactNode;
  modal: React.ReactNode;
}

Como você digita os params em uma rota interceptada de Componente Cliente?

Use React.use() para desempacotar o Promise, pois você não pode usar await em Componentes Cliente.

"use client";
import { use } from "react";
 
export default function Modal({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = use(params);
  return <div>Item {id}</div>;
}

Armadilha: O que acontece com históricos de navegação complexos e múltiplos rotas interceptadas?

Quando você deve usar um modal simples do lado do cliente em vez de interceptar rotas?

O @modal pode ser aninhado dentro de outro @slot?

Não. Slots de rotas paralelas devem ser filhos diretos de um diretório de layout. Você não pode aninhar @modal dentro de outro slot.

Relacionados

Rotas Paralelas - segmentos @slot que habilitam a interceptação
Navegação - useRouter para fechar modais
Rotas Dinâmicas - segmentos parametrizados em rotas interceptadas
Noções Básicas do App Router - visão geral das convenções de arquivo

Interceptando Rotas

Buscar na documentação

Interceptando Rotas