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

180 lines
3.7 KiB
Markdown
Raw Normal View History

---
icon: IconDirectory
title: 'layouts'
head.title: Layouts directory
---
# Layouts directory
2021-06-30 16:32:22 +00:00
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`.)
2021-06-30 16:32:22 +00:00
If you only have a single layout in your application, we recommend using [app.vue](/guide/directory-structure/app) instead.
2021-06-30 16:32:22 +00:00
::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
2021-06-30 16:32:22 +00:00
Add a `~/layouts/default.vue`:
2021-06-30 16:32:22 +00:00
```vue [layouts/default.vue]
2021-06-30 16:32:22 +00:00
<template>
<div>
Some default layout shared across all pages
2021-06-30 16:32:22 +00:00
<slot />
</div>
</template>
```
In a layout file, the content of the layout will be loaded in the `<slot />`, rather than using a special component.
2021-06-30 16:32:22 +00:00
If you use a `app.vue` you will also need to add `<NuxtLayout>`:
```vue [app.vue]
<template>
<NuxtLayout>
some page content
</NuxtLayout>
</template>
```
## Setting another layout
```bash
-| layouts/
---| default.vue
---| custom.vue
```
You can directly override the default layout like this:
```vue{}[app.vue]
<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
```vue{}[pages/index.vue]
2021-06-30 16:32:22 +00:00
<script>
// This will also work in `<script setup>`
definePageMeta({
2021-06-30 16:32:22 +00:00
layout: "custom",
});
2021-06-30 16:32:22 +00:00
</script>
```
```vue{}[app.vue]
<template>
<NuxtLayout>
<NuxtPage />
</NuxtLayout>
</template>
```
```vue [layouts/custom.vue]
<template>
<div>
Some *custom* layout
<slot />
</div>
</template>
```
```vue [layouts/default.vue]
2021-06-30 16:32:22 +00:00
<template>
<div>
A *default* layout
<slot />
</div>
2021-06-30 16:32:22 +00:00
</template>
```
::
::alert{type=info}
Learn more about [defining page meta](/guide/directory-structure/pages#page-metadata).
::
## Changing the layout dynamically
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>
```
2022-04-09 09:25:13 +00:00
:LinkExample{link="/examples/routing/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
```vue [pages/index.vue]
<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>
```
```vue [layouts/custom.vue]
<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).
::