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.

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

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

  1. -| layouts/
  2. ---| custom.vue
  3. -| 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:

layouts/custom.vue

  1. <template>
  2.   <div>
  3.     Some shared layout content:
  4.     <slot />
  5.   </div>
  6. </template>

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

app.vue

  1. <template>
  2.   <NuxtLayout name="custom">
  3.     Hello world!
  4.   </NuxtLayout>
  5. </template>

Example: setting the layout with ~/pages

  1. -| layouts/
  2. ---| custom.vue
  3. -| pages/
  4. ---| index.vue

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

pages/index.vue

  1. <script>
  2. // This will also work in `<script setup>`
  3. definePageMeta({
  4.   layout: "custom",
  5. });
  6. </script>

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.

  1. <template>
  2.   <NuxtLayout name="custom">
  3.     <template #header> Some header template content. </template>
  5.     The rest of the page
  6.   </NuxtLayout>
  7. </template>
  9. <script setup>
  10. definePageMeta({
  11.   layout: false,
  12. });
  13. </script>

Example: changing the layout

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

  1. <template>
  2.   <div>
  3.     <button @click="enableCustomLayout">Update layout</button>
  4.   </div>
  5. </template>
  7. <script setup>
  8. const route = useRoute()
  9. function enableCustomLayout () {
  10.   route.meta.layout = "custom"
  11. }
  12. definePageMeta({
  13.   layout: false,
  14. });
  15. </script>

🔎

Read and edit a live example in Examples > Routing > Layouts