Correct Nesting Order: RouterView, Transition, KeepAlive, Suspense

Rule

When combining <Suspense> with <Transition>, <KeepAlive>, and <RouterView>, the nesting order must be: RouterView -> Transition -> KeepAlive -> Suspense. Incorrect nesting causes components to not work together properly.

Why This Matters

Each of these components wraps and controls its child in specific ways. Incorrect nesting leads to:

Transitions not animating
Components not being cached by KeepAlive
Suspense not catching async dependencies
Subtle bugs that are hard to diagnose

Bad Code

<template>
  <!-- Wrong order - Suspense wrapping KeepAlive -->
  <RouterView v-slot="{ Component }">
    <Suspense>
      <KeepAlive>
        <Transition mode="out-in">
          <component :is="Component" />
        </Transition>
      </KeepAlive>
    </Suspense>
  </RouterView>
</template>

<template>
  <!-- Wrong - KeepAlive outside Transition -->
  <RouterView v-slot="{ Component }">
    <KeepAlive>
      <Transition mode="out-in">
        <Suspense>
          <component :is="Component" />
        </Suspense>
      </Transition>
    </KeepAlive>
  </RouterView>
</template>

Good Code

<template>
  <RouterView v-slot="{ Component }">
    <template v-if="Component">
      <Transition mode="out-in">
        <KeepAlive>
          <Suspense>
            <!-- Main content -->
            <component :is="Component" />

            <!-- Loading state -->
            <template #fallback>
              <div class="route-loading">
                Loading...
              </div>
            </template>
          </Suspense>
        </KeepAlive>
      </Transition>
    </template>
  </RouterView>
</template>

With Selective KeepAlive

<template>
  <RouterView v-slot="{ Component, route }">
    <template v-if="Component">
      <Transition :name="route.meta.transition || 'fade'" mode="out-in">
        <KeepAlive :include="cachedViews">
          <Suspense :timeout="200">
            <component :is="Component" :key="route.fullPath" />

            <template #fallback>
              <RouteLoadingSkeleton :route="route" />
            </template>
          </Suspense>
        </KeepAlive>
      </Transition>
    </template>
  </RouterView>
</template>

<script setup>
import { computed } from 'vue'
import { useRoute } from 'vue-router'

const route = useRoute()

// Only cache specific routes
const cachedViews = computed(() => ['Dashboard', 'Profile', 'Settings'])
</script>

Why This Order?

RouterView - Provides the route component via scoped slot
Transition - Needs to wrap what animates (the cached/suspended content)
KeepAlive - Caches the Suspense + component together
Suspense - Directly wraps the async component to handle loading

Important Notes

Vue Router's lazy-loaded route components (via dynamic imports) don't trigger Suspense directly
Only async components within the route component trigger Suspense
Use v-if="Component" to handle the case when no route matches
The :key on the component can force re-render and re-trigger Suspense

Key Points

Always follow the order: RouterView -> Transition -> KeepAlive -> Suspense
Each wrapper serves a specific purpose in this hierarchy
Use mode="out-in" on Transition to prevent overlap during route changes
Consider using route-based keys for fine-grained control over when Suspense triggers

3.6 KiB Raw Permalink Blame History