Pular para o conteúdo
Documentação do Next.js PT-BR

Layouts e páginas

O Next.js usa roteamento baseado no sistema de arquivos, o que significa que você pode usar pastas e arquivos para definir rotas. Esta página vai mostrar como criar layouts e páginas e como navegar entre eles.

Criando uma página

Uma página é uma interface (UI) renderizada em uma rota específica. Para criar uma página, adicione um arquivo page dentro do diretório app e exporte por padrão um componente React. Por exemplo, para criar uma página inicial (/):

Arquivo especial page.jsArquivo especial page.js
app/page.tsx
export default function Page() {
  return <h1>Hello Next.js!</h1>
}

Criando um layout

Um layout é uma interface compartilhada entre várias páginas. Na navegação, os layouts preservam o estado, continuam interativos e não renderizam de novo.

Você pode definir um layout exportando por padrão um componente React de um arquivo layout. O componente deve receber uma prop children, que pode ser uma página ou outro layout.

Por exemplo, para criar um layout que recebe sua página inicial como filho, adicione um arquivo layout dentro do diretório app:

Arquivo especial layout.jsArquivo especial layout.js
app/layout.tsx
export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        {/* Layout UI */}
        {/* Place children where you want to render a page or nested layout */}
        <main>{children}</main>
      </body>
    </html>
  )
}

O layout acima é chamado de layout raiz porque está definido na raiz do diretório app. O layout raiz é obrigatório e deve conter as tags html e body.

Criando uma rota aninhada

Uma rota aninhada é uma rota composta por vários segmentos de URL. Por exemplo, a rota /blog/[slug] é composta por três segmentos:

  • / (Segmento raiz)
  • blog (Segmento)
  • [slug] (Segmento folha)

No Next.js:

  • Pastas são usadas para definir os segmentos de rota que correspondem aos segmentos de URL.
  • Arquivos (como page e layout) são usados para criar a interface exibida para um segmento.

Para criar rotas aninhadas, você pode colocar pastas umas dentro das outras. Por exemplo, para adicionar uma rota para /blog, crie uma pasta chamada blog no diretório app. Depois, para tornar /blog acessível publicamente, adicione um arquivo page.tsx:

Hierarquia de arquivos mostrando a pasta blog e um arquivo page.jsHierarquia de arquivos mostrando a pasta blog e um arquivo page.js
app/blog/page.tsx
// Dummy imports
import { getPosts } from '@/lib/posts'
import { Post } from '@/ui/post'

export default async function Page() {
  const posts = await getPosts()

  return (
    <ul>
      {posts.map((post) => (
        <Post key={post.id} post={post} />
      ))}
    </ul>
  )
}

Você pode continuar aninhando pastas para criar rotas aninhadas. Por exemplo, para criar uma rota para um post específico do blog, crie uma nova pasta [slug] dentro de blog e adicione um arquivo page:

Hierarquia de arquivos mostrando a pasta blog com uma pasta slug aninhada e um arquivo page.jsHierarquia de arquivos mostrando a pasta blog com uma pasta slug aninhada e um arquivo page.js
app/blog/[slug]/page.tsx
export function generateStaticParams() {}

export default function Page() {
  return <h1>Hello, Blog Post Page!</h1>
}

Colocar o nome de uma pasta entre colchetes (por exemplo, [slug]) cria um segmento de rota dinâmico, usado para gerar várias páginas a partir de dados. Por exemplo, posts de blog, páginas de produto etc.

Aninhando layouts

Por padrão, os layouts na hierarquia de pastas também são aninhados, o que significa que eles envolvem os layouts filhos pela prop children. Você pode aninhar layouts adicionando layout dentro de segmentos de rota (pastas) específicos.

Por exemplo, para criar um layout para a rota /blog, adicione um novo arquivo layout dentro da pasta blog.

Hierarquia de arquivos mostrando o layout raiz envolvendo o layout do blogHierarquia de arquivos mostrando o layout raiz envolvendo o layout do blog
app/blog/layout.tsx
export default function BlogLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return <section>{children}</section>
}

Se você combinar os dois layouts acima, o layout raiz (app/layout.js) vai envolver o layout do blog (app/blog/layout.js), que vai envolver o blog (app/blog/page.js) e a página de post do blog (app/blog/[slug]/page.js).

Criando um segmento dinâmico

Segmentos dinâmicos permitem criar rotas geradas a partir de dados. Por exemplo, em vez de criar manualmente uma rota para cada post do blog, você pode criar um segmento dinâmico que gera as rotas com base nos dados dos posts.

Para criar um segmento dinâmico, coloque o nome do segmento (pasta) entre colchetes: [segmentName]. Por exemplo, na rota app/blog/[slug]/page.tsx, o [slug] é o segmento dinâmico.

app/blog/[slug]/page.tsx
export default async function BlogPostPage({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)

  return (
    <div>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </div>
  )
}

Saiba mais sobre Segmentos dinâmicos e as props params.

Layouts dentro de segmentos dinâmicos também podem acessar as props params.

Renderizando com parâmetros de busca

Em uma página de Server Component, você pode acessar os parâmetros de busca usando a prop searchParams:

app/page.tsx
export default async function Page({
  searchParams,
}: {
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
  const filters = (await searchParams).filters
}

Usar searchParams faz sua página entrar em Dynamic Rendering, porque ela precisa de uma requisição recebida para ler os parâmetros de busca.

Client Components podem ler os parâmetros de busca usando o hook useSearchParams.

Saiba mais sobre useSearchParams em rotas com prerendering e Dynamic Rendering.

O que usar e quando

  • Use a prop searchParams quando precisar dos parâmetros de busca para carregar dados da página (por exemplo, paginação ou filtragem vinda de um banco de dados).
  • Use useSearchParams quando os parâmetros de busca forem usados apenas no cliente (por exemplo, filtrar uma lista já carregada por props).
  • Como uma pequena otimização, você pode usar new URLSearchParams(window.location.search) em callbacks ou manipuladores de eventos para ler os parâmetros de busca sem disparar novas renderizações.

Criando links entre páginas

Você pode usar o componente <Link> para navegar entre rotas. <Link> é um componente embutido do Next.js que estende a tag HTML <a> para oferecer prefetching e navegação no lado do cliente.

Por exemplo, para gerar uma lista de posts do blog, importe <Link> de next/link e passe uma prop href para o componente:

app/ui/post.tsx
import Link from 'next/link'
import { getPosts } from '@/lib/posts'

export default async function Posts() {
  const posts = await getPosts()

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.slug}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

Bom saber: <Link> é a forma principal de navegar entre rotas no Next.js. Você também pode usar o hook useRouter para navegações mais avançadas.

Helpers de props de rota

O Next.js expõe tipos utilitários que inferem params e slots nomeados a partir da estrutura das suas rotas:

  • PageProps: props para componentes page, incluindo params e searchParams.
  • LayoutProps: props para componentes layout, incluindo children e quaisquer slots nomeados (por exemplo, pastas como @analytics).

Estes são helpers globais, gerados ao executar next dev, next build ou next typegen.

app/blog/[slug]/page.tsx
export default async function Page(props: PageProps<'/blog/[slug]'>) {
  const { slug } = await props.params
  return <h1>Blog post: {slug}</h1>
}
app/dashboard/layout.tsx
export default function Layout(props: LayoutProps<'/dashboard'>) {
  return (
    <section>
      {props.children}
      {/* If you have app/dashboard/@analytics, it appears as a typed slot: */}
      {/* {props.analytics} */}
    </section>
  )
}

Bom saber

  • Rotas estáticas resolvem params para {}.
  • PageProps e LayoutProps são helpers globais, sem necessidade de importação.
  • Os tipos são gerados durante next dev, next build ou next typegen.

Referência da API

Saiba mais sobre os recursos mencionados nesta página lendo a Referência da API.