From 0a05b8875f68ac5f559642e4b9ba2c119d68d3b8 Mon Sep 17 00:00:00 2001
From: Noel De Martin <noel@noeldemartin.com>
Date: Wed, 30 Oct 2024 16:09:55 +0700
Subject: [PATCH] docs: document appear transition behaviour (#2392)

---
 packages/docs/guide/advanced/transitions.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/packages/docs/guide/advanced/transitions.md b/packages/docs/guide/advanced/transitions.md
index 3af7f6ada..9a1dc98be 100644
--- a/packages/docs/guide/advanced/transitions.md
+++ b/packages/docs/guide/advanced/transitions.md
@@ -80,5 +80,23 @@ Vue might automatically reuse components that look alike, avoiding any transitio
 </router-view>
 ```
 
+## Respecting `appear` transitions behaviour
+
+Usually, enter animations are ignored on the initial render unless you're using the `appear` prop. But you'll notice that route components don't respect this behaviour. This happens because the route component is not available in the initial render.
+
+You can fix this by making sure that the `<transition>` component isn't rendered until the first route component has been loaded:
+
+```vue-html
+<router-view v-slot="{ Component }">
+  <transition v-if="Component" name="fade">
+    <component :is="Component" />
+  </transition>
+</router-view>
+```
+
+Alternatively, you can also await on the router's [`isReady`](https://router.vuejs.org/api/interfaces/Router.html#isReady) method which returns a promise.
+
+Finally, you can support for more complex scenarios [combining the `<Suspense>` and `<KeepAlive>` components](https://vuejs.org/guide/built-ins/suspense.html#combining-with-other-components).
+
 <!-- TODO: interactive example -->
 <!-- See full example [here](https://github.com/vuejs/vue-router/blob/dev/examples/transitions/app.js). -->