Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 72 ยท Routing

Pages and Layouts

Create pages with page.tsx and shared UI with layout.tsx, write the required root layout, nest layouts and see why they keep their state between pages.

Two file names do most of the work in the App Router: page.tsx and layout.tsx. A page is the unique content of one URL. A layout is the shared frame around one or more pages, such as a header, a sidebar or a footer. Together they give you a website whose frame stays put while the content inside it changes.

In this lesson you will write both, learn the rules for the required root layout, nest layouts inside each other and find out why layouts keep their state when you navigate. The tsx code is real Next.js and read-only. The live examples are stand-ins: a React program that shows layout state surviving navigation, and a Node.js program that works out which layouts wrap a URL.

Pages

A page is a React component that is the default export of a file named page.tsx (or .jsx, .ts, .js). The folder the file sits in decides the URL, which you will study properly in File-Based Routing. For now: app/page.tsx is the home page, and app/about/page.tsx is /about.

TSX
// app/about/page.tsx (read-only)
export default function AboutPage() {
  return (
    <section>
      <h1>About us</h1>
      <p>We build small tools for teams that like simple things.</p>
    </section>
  );
}

A few facts to keep in mind:

  • The component name does not matter to Next.js. The file name page and the default export do.
  • Pages are Server Components by default, so they can be async and can read data directly. You will use that heavily from React Server Components on.
  • A route is only public when it has a page file. A folder without one is just a folder.

Layouts

A layout is a component that receives a children prop and wraps it. The children are either the page or another nested layout below it.

TSX
// app/dashboard/layout.tsx (read-only)
import Link from 'next/link';

export default function DashboardLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="dashboard">
      <nav>
        <Link href="/dashboard">Overview</Link>
        <Link href="/dashboard/settings">Settings</Link>
      </nav>
      <section>{children}</section>
    </div>
  );
}

This layout applies to app/dashboard/page.tsx, to app/dashboard/settings/page.tsx and to every other route below the dashboard folder. You write the frame once and each page only provides its own content. The Link component is covered in Linking and Navigation.

Pages and layouts

Page The unique content of one URL.
Layout Shared frame around many pages.
children Where the page or inner layout goes.

A layout never decides which page shows. The URL does.

1 / 2

The root layout

Every app must have a root layout at app/layout.tsx. It is the top of the tree and the only layout that contains the <html> and <body> tags. Because it wraps every page, it is the right place for the page language, global styles, fonts and site-wide providers.

TSX
// app/layout.tsx (read-only)
import type { Metadata } from 'next';
import './globals.css';

export const metadata: Metadata = {
  title: 'My App',
  description: 'A small Next.js app',
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <header>My App</header>
        {children}
        <footer>Made with Next.js</footer>
      </body>
    </html>
  );
}

Things to remember:

  • It must render <html> and <body>. Next.js does not add them for you. Nested layouts must not render them.
  • It is a Server Component. It cannot use state or event handlers directly. Put those in a small Client Component and render that inside the layout.
  • The metadata export sets the <title> and meta tags. Pages and layouts can both export it, and values are merged. The full story is in Metadata and SEO.
  • If you delete the file in development, Next.js creates a basic one for you, but you should always write your own.

In the Pages Router, the same job was split across _app.tsx and _document.tsx. In the App Router, one root layout replaces both.

Nested layouts

Layouts nest by folder. A layout wraps everything below it, and the result is a chain from the root layout down to the page:

flowchart TD
    A["app/layout.tsx<br/>RootLayout"] --> B["app/dashboard/layout.tsx<br/>DashboardLayout"]
    B --> C["app/dashboard/settings/page.tsx<br/>SettingsPage"]

For /dashboard/settings, the page is passed as children to the dashboard layout, which is passed as children to the root layout.

In plain React terms, the URL /dashboard/settings renders this tree:

TSX
// What Next.js builds (read-only, simplified)
<RootLayout>
  <DashboardLayout>
    <SettingsPage />
  </DashboardLayout>
</RootLayout>

Each folder can have its own layout, so a blog section can have a different frame from an account section while both share the root layout. If a folder has no layout.tsx, it simply adds nothing to the chain.

Layouts keep their state

Here is the feature that makes layouts special. When you move between two pages that share a layout, the layout is not unmounted or re-created. It stays on screen with its state intact: a search box keeps its text, a sidebar keeps its scroll position and open sections, a counter keeps its count. Only the page inside changes.

That behavior also saves work, because the layout does not need to render again for each page. The next section lets you see it.

Real framework or stand-in? This React program stands in for Next.js's router. It uses hash links (#/dashboard) because the sandbox has no server, and a few lines decide which layouts and page to render. The effect it shows is the same one React gives real Next.js: components that stay at the same place in the tree keep their state. The real client router adds payload fetching, caching and prefetching on top.

Layouts keep state, pages do not

Try this sequence: raise the layout counter and the page counter, then click between Overview and Settings. The layout counter and the text in the box survive, while the page counter restarts at zero because each page is a different component. Then go Home: the dashboard layout leaves the screen and its state is gone, since the layout itself is no longer in the tree.

If you want the opposite, a frame that resets on every navigation, Next.js has template.tsx. That is the subject of Templates and Other Special Files.

What layouts cannot do

Because a layout stays mounted while its children change, a few things are off the table:

  • Layouts do not receive searchParams. The query string can change without the layout re-rendering, so it would go stale. Read it in a page, or in a Client Component with a hook (Search Params and Navigation Hooks).
  • A layout cannot pass data to its children. There is no prop passing between a layout and the page below it. Fetch the data where you need it; Next.js and React deduplicate identical requests, which Fetching Data in Server Components explains.
  • A layout cannot easily know the current URL. For active-link styling, use a small Client Component with usePathname.

Try it: which layouts wrap a URL?

The second stand-in is a Node.js program that takes a list of files and a URL and works out the chain of layouts around the page, the same walk Next.js performs from the root down. It is a model of the idea, using file names only.

Node.js Find the layout chain for a URL

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice /blog: there is no blog/layout.tsx, so only the root layout wraps it. And /missing has no page file at all, so there is nothing to show. In the real framework that case renders your not-found UI, covered in loading.tsx, error.tsx and not-found.tsx.

Common mistakes

  • Forgetting . A layout that does not render children hides the page completely.
  • Adding <html> and <body> to a nested layout. Only the root layout renders them.
  • Expecting a layout's state to reset. It will not. Use template.tsx, or a key, if you need that.
  • Using hooks in a layout directly. A layout is a Server Component by default. Move interactive parts into a Client Component.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which file must exist at the top of every App Router app?

    The root layout is required. It is the only layout that renders the html and body tags.
  2. 2. You navigate from /dashboard to /dashboard/settings. What happens to the dashboard layout and its state?

    Layouts above the change are preserved. This is why a sidebar or search box does not lose its state between sibling pages.
  3. 3. A layout does not render {children}. What is the result?

    children is where the page or nested layout goes. If you leave it out, nothing from below the layout appears.
  4. 4. Which of these can a layout NOT do?

    Layouts do not re-render when the query string changes, so they do not receive searchParams. Read them in a page or with a client hook.
  5. 5. What makes app/reports/page.tsx different from app/reports/helpers.ts?

    Only special files such as page and route make a folder public. Other files are ignored by the router.

Summary

  • A page.tsx default export is the unique UI of a route, and a route is only public when it has one.
  • A layout.tsx wraps its children, and layouts nest by folder from the root layout down to the page.
  • The root layout is required and is the only one that renders <html> and <body>.
  • Layouts stay mounted during navigation, so their state survives while pages below them change.
  • Layouts do not get searchParams, cannot pass data to children and are Server Components by default.

Next: File-Based Routing