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

134 lines
2.9 KiB
Markdown

---
icon: IconDirectory
title: 'layouts'
head.title: 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.
If you only have a single layout in your application, we recommend using [app.vue](/guide/directory-structure/app) 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`
```bash
-| 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:
```vue{}[layouts/custom.vue]
<template>
<div>
Some shared layout content:
<slot />
</div>
</template>
```
Here's how you might use that layout in `app.vue`:
```vue{}[app.vue]
<template>
<NuxtLayout name="custom">
Hello world!
</NuxtLayout>
</template>
```
## Example: setting the layout with `~/pages`
```bash
-| layouts/
---| custom.vue
-| pages/
---| index.vue
```
You can set your layout within your page components like this:
```vue{}[pages/index.vue]
<script>
// This will also work in `<script setup>`
definePageMeta({
layout: "custom",
});
</script>
```
::alert{type=info}
Learn more about [defining page meta](/guide/directory-structure/pages#page-metadata).
::
## 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
```vue [layouts/custom.vue]
<template>
<div>
<header>
<slot name="header">
Default header content
</slot>
</header>
<main>
<slot />
</main>
</div>
</template>
```
```vue [pages/index.vue]
<template>
<NuxtLayout name="custom">
<template #header> Some header template content. </template>
The rest of the page
</NuxtLayout>
</template>
<script setup>
definePageMeta({
layout: false,
});
</script>
```
::
## Example: changing the layout
You can also use a ref or computed property for your layout.
```vue
<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"}