From 040b36a49184810e2575a18b283d83e0faa212da Mon Sep 17 00:00:00 2001
From: Krutie Patel <krutie.patel@gmail.com>
Date: Tue, 2 Aug 2022 23:43:40 +1000
Subject: [PATCH] docs(api): add `<NuxtLayout>` component docs (#6264)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com>
---
 .../3.api/2.components/2.nuxt-layout.md       | 58 ++++++++++++++++++-
 1 file changed, 56 insertions(+), 2 deletions(-)

diff --git a/docs/content/3.api/2.components/2.nuxt-layout.md b/docs/content/3.api/2.components/2.nuxt-layout.md
index e32f5b6d00..1c94d7dc59 100644
--- a/docs/content/3.api/2.components/2.nuxt-layout.md
+++ b/docs/content/3.api/2.components/2.nuxt-layout.md
@@ -1,7 +1,61 @@
 # `<NuxtLayout>`
 
-::ReadMore{link="/guide/directory-structure/app"}
+You can use `<NuxtLayout />` component to activate `default` layout on `app.vue` or `error.vue`.
+
+```vue [/app.vue]
+<template>
+  <NuxtLayout>
+    some page content
+  </NuxtLayout>
+</template>
+```
+
+`<NuxtLayout />` can be used to override `default` layout on `app.vue`, `error.vue` or even page components found in the `/pages` directory.
+
+## `name` prop
+
+`<NuxtLayout />` component accepts the `name` prop, which you can pass to use a non-default layout, where `name` can be a static string, reactive reference or a computed property. It **must** match the name of the corresponding layout file in the `/layouts` directory.
+
+### Examples
+
+```vue [pages/index.vue]
+<template>
+  <NuxtLayout :name="layout">
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+
+<script setup>
+// layouts/custom.vue
+const layout = 'custom'
+</script>
+```
+
+::alert{icon=👉}
+Please note the layout name is normalized to kebab-case, so if your layout file is named `errorLayout.vue`, it will become `error-layout` when passed as a `name` property to `<NuxtLayout />`.
 ::
 
-::NeedContribution
+```vue [/error.vue]
+<template>
+  <NuxtLayout name="error-layout">
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+```
+
+## Layout and transition
+
+`<NuxtLayout />` renders incoming content via `<slot />`, which is then wrapped around Vue’s `<Transition />` component to activate layout transition. For this to work as expected, it is recommended that `<NuxtLayout />` is **not** the root element of the page component.
+
+```vue [pages/index.vue]
+<template>
+  <div>
+    <NuxtLayout name="custom">
+      <template #header> Some header template content. </template>
+    </NuxtLayout>
+  </div>
+</template>
+```
+
+::ReadMore{link="/guide/directory-structure/layouts"}
 ::