Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 32 ยท Pages and routing

Nested routes and layouts

Build parent and child routes with NuxtPage, share page frames with the layouts folder, switch layouts with definePageMeta, and handle errors with error.vue.

Real sites share structure. A user section has a sidebar that stays while the content on the right changes. An admin area has a different frame from the public site. A broken URL needs a friendly error screen. Nuxt has a tool for each: nested routes for sections inside a page, layouts for whole-page frames, and error.vue for failures.

They stack from the outside in. The layout wraps everything, then a parent page wraps its children, then the child page fills the last slot. This lesson builds on File-based routing and Dynamic routes and params.

Frames inside frames

Layout Header and footer around any page.
Parent page A section with its own sidebar.
Child page The content that changes.

Each outer frame shows the next one in a slot or NuxtPage.

1 / 2

Nested routes

A page becomes a parent when a folder with the same name sits next to it:

TEXT
app/pages/
  users.vue            the parent: sidebar and a place for the child
  users/
    index.vue          /users          (the child shown at the parent's own URL)
    [id].vue           /users/42
    settings.vue       /users/settings

The parent must say where its child goes, with <NuxtPage />:

VUE
<!-- app/pages/users.vue (read-only) -->
<template>
  <div class="users-layout">
    <aside>
      <NuxtLink to="/users">All users</NuxtLink>
      <NuxtLink to="/users/settings">Settings</NuxtLink>
    </aside>
    <section>
      <NuxtPage />
    </section>
  </div>
</template>

Visiting /users/42 renders users.vue, and the <NuxtPage /> inside it renders users/[id].vue. Moving between children keeps the sidebar, so any state in it survives. If you forget the inner <NuxtPage />, the parent shows but the child never appears, which is the most common nested-routing bug.

If you want users/[id].vue without a shared parent, do not create users.vue. A folder alone does not nest anything. Use nesting only when the parent has real content of its own.

The first stand-in shows the mechanism with plain functions. Each page is a function that receives the already-rendered child (its "outlet") and returns HTML. Rendering a URL means building the chain from the inside out, which is also how Vue renders nested router views. The code is a model, not Nuxt's implementation.

JS Nested pages with an outlet

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

No output.

Look at how the aside appears in both outputs while the section changes. That is what <NuxtPage /> inside users.vue achieves.

Layouts

A layout is a component in layouts/ that wraps pages. It has a <slot /> where the page goes:

VUE
<!-- app/layouts/default.vue (read-only) -->
<template>
  <div>
    <header><NuxtLink to="/">My site</NuxtLink></header>
    <main>
      <slot />
    </main>
    <footer>Copyright</footer>
  </div>
</template>

To use layouts, put <NuxtLayout> around <NuxtPage /> in app.vue:

VUE
<!-- app/app.vue (read-only) -->
<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

The file layouts/default.vue is applied to every page that does not ask for another one. A page picks a different layout in definePageMeta. The name is the file name in kebab-case:

VUE
<!-- app/pages/admin/index.vue (read-only) -->
<script setup lang="ts">
definePageMeta({ layout: 'admin' })       // uses layouts/admin.vue
</script>

Pass layout: false to render a page with no layout at all, which is useful for a login screen or a printable page.

Keep a single root element in layouts and pages. Comments or several sibling elements at the top level can break page transitions and cause confusing warnings.

Switching layouts at runtime

definePageMeta is static. For a layout that depends on something at runtime, such as the user's role, use setPageLayout() in a middleware or plugin (Navigation and route middleware):

TypeScript
// app/middleware/pick-layout.global.ts (read-only)
export default defineNuxtRouteMiddleware((to) => {
  const { user } = useAuth()      // your own composable
  if (user.value?.role === 'admin' && to.path.startsWith('/dashboard')) {
    setPageLayout('admin')
  }
})

You can also override the layout where it is used: <NuxtLayout :name="layoutName"> takes a reactive name. Prefer the page-level layout setting for the normal case, because it is easier to find when you read a page.

flowchart TD
  A["app.vue"] --> L["NuxtLayout picks layouts/admin.vue"]
  L --> S["layout slot"]
  S --> P["pages/users.vue (parent)"]
  P --> N["NuxtPage inside parent"]
  N --> C["pages/users/[id].vue (child)"]

From the outside in: layout, then parent page, then child page.

The second stand-in picks a layout the way Nuxt does: the page's own setting wins, false means no layout, a runtime override (like setPageLayout) beats the page, and otherwise the default applies. If a named layout does not exist, it falls back to the default with a warning. The real behavior has more cases, so check it against your Nuxt version.

JS Choosing a layout

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

No output.

The error page

When something fails, such as a 404 or a thrown error during rendering, Nuxt shows your error.vue. It lives next to app.vue (in app/) and receives the error as a prop. It is not a page and not inside a layout, so import or place any header and footer yourself:

VUE
<!-- app/error.vue (read-only) -->
<script setup lang="ts">
const props = defineProps<{
  error: { statusCode: number; statusMessage?: string; message: string }
}>()
const goHome = () => clearError({ redirect: '/' })
</script>

<template>
  <div>
    <h1>{{ error.statusCode }}</h1>
    <p>{{ error.statusMessage || error.message }}</p>
    <button @click="goHome">Back to the home page</button>
  </div>
</template>

Three helpers matter:

  • createError({ statusCode: 404, statusMessage: 'Not found' }) creates an error object. Throw it from a page, middleware or API handler. On the server a thrown error leads to the error page and the matching HTTP status. Pass fatal: true if you throw it during client-side navigation and want the full-screen error page.
  • showError(...) displays the error page programmatically.
  • clearError({ redirect: '/' }) removes the error and, optionally, navigates away. Without it the visitor stays on the error screen.

A catch-all page such as [...slug].vue can throw createError({ statusCode: 404 }) itself, so unknown URLs also produce a proper 404 status for search engines instead of a "soft 404" that returns 200.

Common mistakes

  • No <NuxtPage /> in a parent page. The child never renders.
  • No <NuxtLayout> in app.vue. Layouts exist but are never applied.
  • Layout without a <slot />. The page has nowhere to go.
  • Multiple root elements in a layout or page.
  • Forgetting that error.vue is outside layouts. It does not inherit the header or footer.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What makes pages/users.vue a parent of pages/users/[id].vue?

    The folder next to the file creates the nesting, and the parent needs <NuxtPage /> to show its child.
  2. 2. How does a page choose the layouts/admin.vue layout?

    definePageMeta takes the layout name, which is the file name in kebab-case. layout: false disables layouts.
  3. 3. What must a layout file contain so that pages appear inside it?

    The layout's slot is where <NuxtLayout> places the page.
  4. 4. Where does error.vue live, and does it get wrapped in a layout?

    error.vue sits next to app.vue and renders outside layouts, so add any chrome you want to it yourself.

Summary

  • A page with a same-name folder is a parent; it renders its child with <NuxtPage />.
  • Layouts live in layouts/, use a <slot />, and are applied by <NuxtLayout> in app.vue.
  • definePageMeta({ layout }) picks a layout for a page, layout: false removes it, and setPageLayout() changes it at runtime.
  • Keep a single root element in pages and layouts.
  • error.vue shows failures; use createError, showError and clearError to throw, show and reset errors.

Next, Navigation and route middleware covers moving between pages in code and guarding routes.