Nuxt/docs/content/2.guide/3.directory-structure/6.layouts.md

icon	title	head.title
IconDirectory	layouts	Layouts directory

Layouts directory

Nuxt provides a customizable layouts framework you can use throughout your application, ideal for extracting common UI or code patterns into reusable layout components.

Layouts are placed in the layouts/ directory and will be automatically loaded via asynchronous import when used. Layouts are used by setting a layout property as part of your page metadata (if you are using the ~/pages integration), or by using the <NuxtLayout> component. (Note: The layout name is normalized to kebab-case, so someLayout becomes some-layout.)

If you only have a single layout in your application, we recommend using app.vue instead.

::alert{type=warning} Unlike other components, your layouts must have a single root element to allow Nuxt to apply transitions between layout changes - and this root element cannot be a <slot />. ::

Example: Enabling layouts with app.vue

-| layouts/
---| custom.vue
-| app.vue

In your layout files, you'll need to use <slot /> to define where the content of your layout will be loaded. For example:

<template>
  <div>
    Some shared layout content:
    <slot />
  </div>
</template>

Here's how you might use that layout in app.vue:

<template>
  <NuxtLayout name="custom">
    Hello world!
  </NuxtLayout>
</template>

Example: setting the layout with ~/pages

-| layouts/
---| custom.vue
-| pages/
---| index.vue

You can set your layout within your page components like this:

<script>
// This will also work in `<script setup>`
definePageMeta({
  layout: "custom",
});
</script>

And in your app.vue you need to wrap the NuxtPage component with the NuxtLayout component.

<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

::alert{type=info} Learn more about defining page meta. ::

Example: manual control with ~/pages

Even if you are using the ~/pages integration, you can take full control by using the <NuxtLayout> component (which is globally available throughout your application), by setting layout: false.

::code-group

<template>
  <div>
    <header>
      <slot name="header">
        Default header content
      </slot>
    </header>
    <main>
      <slot />
    </main>
  </div>
</template>

<template>
  <div>
    <NuxtLayout name="custom">
      <template #header> Some header template content. </template>

      The rest of the page
    </NuxtLayout>
  </div>
</template>

<script setup>
definePageMeta({
  layout: false,
});
</script>

::

::alert{type=warning} If you use <NuxtLayout> within your pages, make sure it is not the root element (or disable layout/page transitions). ::

Example: changing the layout

You can also use a ref or computed property for your layout.

<template>
  <div>
    <button @click="enableCustomLayout">Update layout</button>
  </div>
</template>

<script setup>
const route = useRoute()
function enableCustomLayout () {
  route.meta.layout = "custom"
}
definePageMeta({
  layout: false,
});
</script>

:LinkExample{link="/examples/routing/layouts"}