Layouts and pages

A frame around every page

In File-system routing you saw that a page.tsx in a folder makes an address a page. A page is the part of the screen that belongs to one address. A layout is the part that several pages share, like a header with the shop's links. You write it once, in a file named layout.tsx, and Next.js puts each page inside it.

Here is the tea shop with one layout and two pages. Like every example in this lesson, it's a real Next.js 16.4.3 project. It was built with next build and run with next start, and what it sent back was recorded. Read app/layout.tsx first, then open the Browser tab and switch between / and /about.

1import Link from "next/link";2 3export const metadata = { title: "Tea shop" };4 5export default function RootLayout({ children }: LayoutProps<"/">) {6  return (7    <html lang="en">8      <body>9        <header>10          <Link href="/">Home</Link> <Link href="/teas">Teas</Link> <Link href="/about">About</Link>11        </header>12        {children}13        <footer>Open every day, 9 to 5.</footer>14      </body>15    </html>16  );17}

app/layout.tsx is the root layout: the layout in the app folder itself, around every page of the app. Its component gets a prop called children, on line 5, and line 12 says where it goes. Above it, lines 9 to 11 are a <header> with three links. Below it, line 13 is a <footer>. Line 3 exports metadata, and its title becomes the page's <title>: the browser frame shows Tea shop.

Now look at the pages. / shows Home Teas About, then Tea shop and Fresh tea, sent to your door., then Open every day, 9 to 5. /about has the same first and last lines, with About us in between. Neither app/page.tsx nor app/about/page.tsx mentions a header or a footer. For each address, Next.js renders the page and passes it to the layout as children. The Network tab shows it in the HTML: the <header>, then the page's <main>, then the <footer>, all inside one <body>.

The root layout: html and body

Every App Router app has a root layout, and it has one job no other file has: it renders the <html> and <body> tags. In the shop, lines 7 and 8 open them, and every page ends up inside that one <body>. The lang="en" on line 7 tells browsers and screen readers the page is in English.

You don't write a <head>. Next.js writes it for you, with the <title> from metadata and the <script> tags the page needs. The Network tab shows them all inside <head>, though the layout never mentions it. (Titles and link previews have their own lesson, The Metadata API.)

What if the tags are missing, or the whole file is? Each version below was built with real Next.js. Guess first, then click.

1import Link from "next/link";2 3export const metadata = { title: "Tea shop" };4 5export default function RootLayout({ children }: LayoutProps<"/">) {6  return (7    <html lang="en">8      <body>9        <header>10          <Link href="/">Home</Link> <Link href="/teas">Teas</Link> <Link href="/about">About</Link>11        </header>12        {children}13        <footer>Open every day, 9 to 5.</footer>14      </body>15    </html>16  );17}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (4/4)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found└ ○ /about ○  (Static)  prerendered as static content

With the tags, the build lists ○ / and ○ /about. ○ means prerendered as static content: the pages' HTML was made during the build. Without the tags, the production build still passes, and Chrome shows the page with no errors, because a browser adds missing <html> and <body> tags while it reads a page. But don't count on that. While you develop, next dev checks for the tags and shows the error Missing <html> and <body> tags in the root layout. You can read that check in Next.js's source: createRootLayoutValidatorStream, which app-render.tsx turns on only in the development server.

With no app/layout.tsx at all, the build stops with an error for each page: page.tsx doesn't have a root layout. To fix this error, make sure every page has a root layout. So a root layout isn't optional. A new project from create-next-app already has one.

Layouts inside folders

The root layout isn't the only place a layout can go. A layout.tsx in any folder goes around the pages in that folder and in the folders below it. The tea pages want a menu of teas that the other pages don't show, so app/teas gets a layout of its own. A layout inside a folder is a nested layout.

1import Link from "next/link";2 3export default function TeasLayout({ children }: LayoutProps<"/teas">) {4  return (5    <section>6      <nav>7        <Link href="/teas/green">Green tea</Link> <Link href="/teas/mint">Mint tea</Link>8      </nav>9      {children}10    </section>11  );12}

app/teas/layout.tsx has the same shape as the root layout, without <html> and <body>: only the root layout renders those. Line 3 types its props as LayoutProps<"/teas">, the layout of the /teas folder. It returns a <section> on line 5 with a <nav> of two tea links on lines 6 to 8, and the page on line 9.

Open the Browser tab and read /teas/green from the top: the root layout's header, then the tea layout's menu, Green tea Mint tea, then the page, then the root layout's footer. Now pick /about: the header, the page and the footer, and no tea menu. /about isn't in the app/teas folder, so the tea layout never wraps it. In the Network tab, the HTML of /teas/green shows the nesting itself: the page's <main> sits inside the tea layout's <section>, which sits inside the root layout's <body>.

Each row is one address in this shop: its page file, and the layouts that wrap it, from the outside in.

/teas gets the tea layout too: a layout wraps the page.tsx in its own folder as well as the pages below. The Terminal tab lists every route as ○. Layouts don't add routes; only page files do.

Layouts keep their state between pages

Layouts do more than save typing. When a visitor clicks a Link to a page under the same root layout, as every page in this shop is, Next.js makes a client-side navigation: the page's JavaScript changes the address and swaps the page part, without loading a whole new HTML page. Next.js's docs say that on such a navigation, layouts keep their state, stay interactive and don't render again. You can watch it happen.

For that, the tea layout gets a cup counter. It needs state and a click handler, so it's a Client Component: app/teas/brew-counter.tsx starts with "use client", which marks where the part of the app that also runs in the browser begins. The layout and the pages stay Server Components: they run only on the server, and the browser gets what they rendered. (Server Components explains the two kinds.)

Clicks need a browser with the page's JavaScript running, so these recordings were made in real Chrome. Each version was opened at /teas/green, its Brew a cup button was pressed twice, then the Mint tea link was clicked, then the Green tea link. The Steps tab lists the steps: pick one to see the page right after it, and the requests the page made. Before you pick a version, guess what each counter shows after the click on Mint tea.

1import Link from "next/link";2import BrewCounter from "./brew-counter";3 4export default function TeasLayout({ children }: LayoutProps<"/teas">) {5  return (6    <section>7      <nav>8        <Link href="/teas/green">Green tea</Link> <Link href="/teas/mint">Mint tea</Link>9      </nav>10      <BrewCounter />11      {children}12    </section>13  );14}

In the first version, step 4 shows Mint tea and Cups brewed: 2. The layout stayed on the screen, and only its children changed, so BrewCounter kept its state. Steps 2 and 3 made no requests at all: pressing Brew a cup only updated state in the browser. Step 4 made none either: when the Mint tea link appeared, step 1 had already fetched that page's static shell in the background, which for a page that's all static is the whole page. That's called prefetching, and the next lesson is about it.

The second version puts a counter in each page instead. After the click, Mint tea's counter says 0: it's a different component, in a different page, with state of its own. Step 5 is a surprise if you know older Next.js: back on Green tea, the counter says 2 again. Cache Components is Next.js 16's model for caching and rendering, turned on with cacheComponents: true in next.config.ts, as new projects have it; the Rendering and caching stage teaches it. With it on, Next.js doesn't throw away a page you leave. It hides it with React's Activity, which keeps its state, and shows it again when you come back. At each level of folders, it keeps the page on the screen plus up to two pages you left: in bfcache-state-manager.ts, MAX_BF_CACHE_ENTRIES is 3 with Cache Components on, counting the visible one. The docs say that before Cache Components, a page's state was lost when you left it: only layouts kept theirs.

The third version uses plain <a> tags. Every click shows a document request in the Steps tab: the browser loaded a whole new HTML page, and everything on the old one was thrown away, so the counter is back at 0. A layout keeps its state only across client-side navigations, which is one reason to use Link for your own pages.

What layouts and pages receive

Next.js calls your layouts and pages with props. You've used children. To type the props, every example in this lesson uses two types: LayoutProps and PageProps. You never import them. Next.js writes them for your app when it runs next dev, next build or next typegen, from your folders, so it knows every route. They arrived in Next.js 15.5. Between the angle brackets goes the route, as a string: LayoutProps<"/teas"> for the tea layout, PageProps<"/teas"> for the tea page.

Each row is one prop: whether a layout gets it, and whether a page gets it.

params holds the parts of the address that come from a dynamic segment, a folder with a name in square brackets that matches many addresses. The shop has none yet, so it's {}; Dynamic routes fills it. searchParams holds the query: the part of an address after ?, like sort=price in /teas?sort=price. Both are promises, so you await them. (In Next.js 14 and earlier they were plain objects; Next.js 15 made them promises.)

So the rule is short: a page gets searchParams, and a layout doesn't. The next section shows what happens when a layout asks for it anyway. How a page reads the query, and what that changes about when the page is made, is the Search params and URL state lesson, later in this stage.

What a layout can't read

The table above has two "No" answers for layouts: the query and the current path. Both come from the same fact. A layout doesn't render again when the visitor moves between its pages, so a query or a path it read would soon be out of date. Next.js doesn't give it either. Try to read the query in the tea layout anyway:

1import Link from "next/link";2 3export default async function TeasLayout({ children, searchParams }: LayoutProps<"/teas">) {4  const { sort } = await searchParams;5  return (6    <section>7      <nav>8        <Link href="/teas/green">Green tea</Link> <Link href="/teas/mint">Mint tea</Link>9      </nav>10      <p>Sorted by: {sort}</p>11      {children}12    </section>13  );14}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...app/teas/layout.tsx(3,54): error TS2339: Property 'searchParams' does not exist on type 'LayoutProps<"/teas">'.Failed to type check.

The build stops while it checks types: Property 'searchParams' does not exist on type 'LayoutProps<"/teas">'. The (3,54) in the message points at line 3, where the layout asks for searchParams. It isn't only TypeScript being strict: written in plain JavaScript, with nothing to check its types, the same layout builds, and /teas?sort=price shows searchParams is undefined. The prop simply isn't there.

1import Link from "next/link";2 3export default function TeasLayout({ children, searchParams }) {4  return (5    <section>6      <nav>7        <Link href="/teas/green">Green tea</Link> <Link href="/teas/mint">Mint tea</Link>8      </nav>9      <p>searchParams is {String(searchParams)}</p>10      {children}11    </section>12  );13}

For the path, there's no prop either. To show it in a layout, put a Client Component inside the layout that calls usePathname from next/navigation. Client Components render again on a navigation, so they always have the current path.

1"use client";2 3import { usePathname } from "next/navigation";4 5export default function YouAreHere() {6  const pathname = usePathname();7  return <p>You are at {pathname}</p>;8}

app/teas/you-are-here.tsx starts with "use client" on line 1. Line 6 calls usePathname(), which returns the path without the query, like /teas/green, and line 7 shows it. The tea layout puts <YouAreHere /> above the page. The Steps tab shows the recording from Chrome: step 1 opens /teas/green and the page says You are at /teas/green; after the click on Mint tea, in step 2, it says You are at /teas/mint. The layout didn't render again, but the Client Component inside it did.

Each row is something a layout can't read, and what to use instead.

The last row is about data. A layout can't pass props to the page in children: Next.js renders the page, not your layout. If the layout and the page both need the same data, each one loads it; Parallel and sequential fetching shows how to avoid loading it twice.

Planning the tea shop's layouts

When you add a part to an app, ask who shows it. If every page shows it, it goes in the root layout. If the pages of one folder show it, it goes in that folder's layout. If one address shows it, it goes in that page. And if it needs the query, it goes in a page, because layouts don't get one. Sort these parts of the tea shop:

One more case: some parts sit around a group of pages that don't share a folder in the address, like a sign-in area. Route groups, folders in brackets like (shop), give them a layout without changing any address: Route groups and private folders shows how.

Common mix-ups

• "Each page needs its own header." No. Put it in a layout once; the recorded / and /about both show the root layout's header.
• "The root layout is optional." No. Without app/layout.tsx, next build stops: page.tsx doesn't have a root layout.
• "Every layout renders <html> and <body>." No. Only the root layout does. A nested layout returns ordinary elements, like the tea layout's <section>.
• "A layout renders again on every click." No. On a client-side navigation it stays on the screen; its counter kept 2 from Green tea to Mint tea.
• "A layout keeps its state whatever the link." No. A plain <a> loads a whole new page, and the counter went back to 0.
• "A layout can read the query or the path." No. LayoutProps has neither. Read the query in the page, and the path with usePathname in a Client Component.
• "A nested layout replaces the root layout." No. It sits inside it: /teas/green shows both the header and the tea menu.

Practice exercises

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

app/
  about/
    page.tsx
  teas/
    green/
      page.tsx
    mint/
      page.tsx
    layout.tsx
    page.tsx
  layout.tsx
  page.tsx

export default function AboutPage() {
  return (
    <main>
      <h1>About us</h1>
      <p>Asha and Ravi run the shop.</p>
    </main>
  );
}

// app/account/layout.tsx
export default function AccountLayout({ children }: LayoutProps<"/account">) {
  // Return a <section> with links to /account/orders and /account/address,
  // then the page.
}

import Link from "next/link";

export default function AccountLayout({ children }: LayoutProps<"/account">) {
  return (
    <section>
      <nav>
        <Link href="/account/orders">Orders</Link> <Link href="/account/address">Address</Link>
      </nav>
      {children}
    </section>
  );
}

import BrewCounter from "../brew-counter";

export default function GreenTeaPage() {
  return (
    <main>
      <h1>Green tea</h1>
      <p>Light and fresh. $4 a box.</p>
      <BrewCounter />
    </main>
  );
}

import Link from "next/link";

export default async function TeasLayout({ children, searchParams }: LayoutProps<"/teas">) {
  const { sort } = await searchParams;
  return (
    <section>
      <nav>
        <Link href="/teas/green">Green tea</Link> <Link href="/teas/mint">Mint tea</Link>
      </nav>
      <p>Sorted by: {sort}</p>
      {children}
    </section>
  );
}

import { Suspense } from "react";

const teas = [
  { name: "Green tea", price: 4 },
  { name: "Mint tea", price: 3 },
  { name: "Lemon tea", price: 5 },
];

async function TeaList({ searchParams }: { searchParams: PageProps<"/teas">["searchParams"] }) {
  const { sort } = await searchParams;
  const shown = sort === "price" ? [...teas].sort((a, b) => a.price - b.price) : teas;
  return (
    <ul>
      {shown.map((tea) => (
        <li key={tea.name}>
          {tea.name}: ${tea.price}
        </li>
      ))}
    </ul>
  );
}

export default function TeasPage({ searchParams }: PageProps<"/teas">) {
  return (
    <main>
      <h1>Our teas</h1>
      <Suspense fallback={<p>Loading teas…</p>}>
        <TeaList searchParams={searchParams} />
      </Suspense>
    </main>
  );
}

app/
  about/
    page.tsx
  page.tsx

export default function HomePage() {
  return (
    <main>
      <h1>Tea shop</h1>
      <p>Fresh tea, sent to your door.</p>
    </main>
  );
}

Check your understanding

For each question, ask which folder each file is in, and whether the click loads a whole new page.

Key takeaways

• A page is what one address shows. A layout is what the pages in its folder, and the folders below, share. It puts the page where it renders children.
• The root layout, app/layout.tsx, is required and renders <html> and <body>. Next.js writes the <head>.
• Layouts nest like their folders: the root layout wraps the tea layout, which wraps the tea pages.
• On a client-side navigation, a layout stays on the screen and its Client Components keep their state. With Cache Components, Next.js also keeps up to two pages you left hidden at each level of folders, with their state. A plain <a> loads a new page and keeps nothing.
• LayoutProps gives children and params; PageProps gives params and searchParams, both promises. Next.js writes both types for you.
• A layout can't read the query or the current path. Read the query in the page, and the path with usePathname in a Client Component.

Coming next: Linking and navigating. It shows what Link prefetches, how to mark the current page's link, how to navigate from code, and where the scroll and the focus go after a click.