From: skirtle <65301168+skirtles-code@users.noreply.github.com>
Date: Thu, 23 Nov 2023 08:30:43 +0000 (+0000)
Subject: docs: add a guide to the RouterView slot (#2049)
X-Git-Tag: v4.3.0~55
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b8cc3de0a3a0b247cfbebfcaa94452ae89308fcc;p=thirdparty%2Fvuejs%2Frouter.git

docs: add a guide to the RouterView slot (#2049)

* docs: add a guide to the RouterView slot

* docs: updates to router-view-slot.md based on review feedback
---

diff --git a/packages/docs/.vitepress/config/en.ts b/packages/docs/.vitepress/config/en.ts
index 33dd772c..70042ff0 100644
--- a/packages/docs/.vitepress/config/en.ts
+++ b/packages/docs/.vitepress/config/en.ts
@@ -134,6 +134,10 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
               text: 'Composition API',
               link: '/guide/advanced/composition-api.html',
             },
+            {
+              text: 'RouterView slot',
+              link: '/guide/advanced/router-view-slot.html',
+            },
             {
               text: 'Transitions',
               link: '/guide/advanced/transitions.html',
diff --git a/packages/docs/guide/advanced/router-view-slot.md b/packages/docs/guide/advanced/router-view-slot.md
new file mode 100644
index 00000000..ded51b49
--- /dev/null
+++ b/packages/docs/guide/advanced/router-view-slot.md
@@ -0,0 +1,73 @@
+# RouterView slot
+
+The RouterView component exposes a slot that can be used to render the route component:
+
+```vue-html
+<router-view v-slot="{ Component }">
+  <component :is="Component" />
+</router-view>
+```
+
+The code above is equivalent to using `<router-view />` without the slot, but the slot provides extra flexibility when we want to work with other features.
+
+## KeepAlive & Transition
+
+When working with the [KeepAlive](https://vuejs.org/guide/built-ins/keep-alive.html) component, we would usually want it to keep the route components alive, not the RouterView itself. We can achieve that by putting the KeepAlive inside the slot:
+
+```vue-html
+<router-view v-slot="{ Component }">
+  <keep-alive>
+    <component :is="Component" />
+  </keep-alive>
+</router-view>
+```
+
+Similarly, the slot allows us to use a [Transition](https://vuejs.org/guide/built-ins/transition.html) component to transition between route components:
+
+```vue-html
+<router-view v-slot="{ Component }">
+  <transition>
+    <component :is="Component" />
+  </transition>
+</router-view>
+```
+
+We can also use KeepAlive inside a Transition:
+
+```vue-html
+<router-view v-slot="{ Component }">
+  <transition>
+    <keep-alive>
+      <component :is="Component" />
+    </keep-alive>
+  </transition>
+</router-view>
+```
+
+For more information about using RouterView with the Transition component, see the [Transitions](./transitions) guide.
+
+## Passing props and slots
+
+We can use the slot to pass props or slots to the route component:
+
+```vue-html
+<router-view v-slot="{ Component }">
+  <component :is="Component" some-prop="a value">
+    <p>Some slotted content</p>
+  </component>
+</router-view>
+```
+
+In practice, this usually isn't something you would want to do, as the route components would **all need to use the same props and slots**. See [Passing Props to Route Components](../essentials/passing-props) for other ways to pass props.
+
+## Template refs
+
+Using the slot allows us to put a [template ref](https://vuejs.org/guide/essentials/template-refs.html) directly on the route component:
+
+```vue-html
+<router-view v-slot="{ Component }">
+  <component :is="Component" ref="mainContent" />
+</router-view>
+```
+
+If we put the ref on the `<router-view>` instead then the ref would be populated with the RouterView instance, rather than the route component.
diff --git a/packages/docs/guide/advanced/transitions.md b/packages/docs/guide/advanced/transitions.md
index 613256ab..0d647d63 100644
--- a/packages/docs/guide/advanced/transitions.md
+++ b/packages/docs/guide/advanced/transitions.md
@@ -5,7 +5,7 @@
   title="Learn about route transitions"
 />
 
-In order to use transitions on your route components and animate navigations, you need to use the v-slot API:
+In order to use transitions on your route components and animate navigations, you need to use the [`<RouterView>` slot](./router-view-slot):
 
 ```html
 <router-view v-slot="{ Component }">
diff --git a/packages/docs/guide/essentials/passing-props.md b/packages/docs/guide/essentials/passing-props.md
index 1c1d77cc..65bfb85b 100644
--- a/packages/docs/guide/essentials/passing-props.md
+++ b/packages/docs/guide/essentials/passing-props.md
@@ -81,7 +81,7 @@ Try to keep the `props` function stateless, as it's only evaluated on route chan
 
 ## Via RouterView
 
-You can also pass any props directly via `<RouterView>`:
+You can also pass any props via the [`<RouterView>` slot](../advanced/router-view-slot):
 
 ```vue-html
 <RouterView v-slot="{ Component }">