layout.js

export default function Layout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Promise<{ team: string }>
}): React.ReactNode

A layout is the outermost component of a route segment: it wraps template.js, error.js, loading.js, not-found.js and page.js below it. Its defining property is that it does not re-render on navigation — move between two pages under the same layout and the sidebar keeps its scroll position, the audio element keeps playing, and client state survives.

The app directory must contain a root layout, and that one is the only place <html> and <body> belong. You can have several root layouts (via route groups, or by omitting app/layout.js), but navigating between them forces a full page load rather than a client-side transition.

What trips people up

• No searchParams, no pathname. Because layouts do not re-render, request-varying values would go stale, so they are not available. Use the page's searchParams prop, or usePathname / useSearchParams in a Client Component child.
• A slow layout blocks navigation. loading.js sits below the layout and cannot cover it, so an uncached fetch or a cookies() call in the layout stalls the transition. Wrap that work in its own <Suspense>, or move it into the page.
• Layouts cannot pass data to children. Fetch in both places and let fetch dedupe, or wrap the loader in React's cache.
• Never hand-write <title> or <meta> here — use the Metadata API.

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

export default async function DashboardLayout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Promise<{ team: string }>
}) {
  const { team } = await params

  return (
    <section>
      <header>
        <h1>Welcome to {team}'s Dashboard</h1>
      </header>
      <main>{children}</main>
    </section>
  )
}

import { Suspense } from 'react'
import { NavSkeleton } from './nav-skeleton'
import { DashboardNav } from './dashboard-nav'

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <Suspense fallback={<NavSkeleton />}>
        <DashboardNav />
      </Suspense>
      <main>{children}</main>
    </>
  )
}

'use client'

import { usePathname } from 'next/navigation'
import Link from 'next/link'

export function NavLinks() {
  const pathname = usePathname()

  return (
    <nav>
      <Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
        Home
      </Link>
      <Link
        className={`link ${pathname === '/about' ? 'active' : ''}`}
        href="/about"
      >
        About
      </Link>
    </nav>
  )
}