Nuxt/docs/2.guide/2.directory-structure/1.layouts.md

navigation.icon	title	description	head.title
IconDirectory	layouts	Nuxt provides a layouts framework to extract common UI patterns into reusable layouts.	layouts/

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 adding <NuxtLayout> to your app.vue, and either setting a layout property as part of your page metadata (if you are using the ~/pages integration), or by manually specifying it as a prop to <NuxtLayout>. (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 />. ::

Enabling the Default Layout

Add a ~/layouts/default.vue:

<template>
  <div>
    Some default layout shared across all pages
    <slot />
  </div>
</template>

In a layout file, the content of the layout will be loaded in the <slot />, rather than using a special component.

If you use a app.vue you will also need to add <NuxtLayout>:

<template>
  <NuxtLayout>
    some page content
  </NuxtLayout>
</template>

Setting Another Layout

-| layouts/
---| default.vue
---| custom.vue

You can directly override the default layout like this:

<template>
  <NuxtLayout :name="layout">
    <NuxtPage />
  </NuxtLayout>
</template>

<script setup>
// You might choose this based on an API call or logged-in status
const layout = "custom";
</script>

Alternatively, you can override the default layout per-page like this:

::code-group

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

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

<template>
  <div>
    Some *custom* layout
    <slot />
  </div>
</template>

<template>
  <div>
    A *default* layout
    <slot />
  </div>
</template>

::

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

Changing the Layout Dynamically

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

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

<script setup>
function enableCustomLayout () {
  setPageLayout('custom')
}
definePageMeta({
  layout: false,
});
</script>

::LinkExample{link="/docs/examples/features/layouts"} ::

Overriding a Layout on a Per-page Basis

If you are using the ~/pages integration, you can take full control by setting layout: false and then using the <NuxtLayout> component within the page.

::code-group

<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>

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

::

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