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 33dd772c9210918767867976e2a6d655c1f98a9a..70042ff08fe68ed1c668977e86732a742326ddd3 100644 (file)
--- 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 (file)
index 0000000..ded51b4
--- /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 613256ab04830f45621b8c4a958c3e0ac2a8b3db..0d647d630a88906517eea6ce1a1609510d5f5cc4 100644 (file)
--- 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 1c1d77ccf73d322fbdcf2fb88dd9fcefb4eec494..65bfb85bd76144e940535e93e961bbdf07bfca8d 100644 (file)
--- 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 }">