agent-skills/skills/vue-best-practices/reference/transition-mode-out-in.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
Use mode="out-in" for Sequential Element Transitions	MEDIUM	Without transition mode, entering and leaving elements animate simultaneously, causing overlap and layout issues	best-practice	vue3 transition animation mode out-in in-out

Use mode="out-in" for Sequential Element Transitions

Impact: MEDIUM - By default, Vue's <Transition> runs enter and leave animations simultaneously. This causes the old and new elements to overlap during the transition, often resulting in visual glitches, layout jumping, or elements appearing stacked. Use mode="out-in" to ensure the old element fully animates out before the new one enters.

Task Checklist

• Use mode="out-in" when transitioning between mutually exclusive elements
• This is especially important for buttons, tabs, or content that shouldn't overlap
• Consider mode="in-out" only for specific overlapping effects (rare)
• Without a mode, both animations run in parallel (default behavior)

Problematic Code:

<template>
  <!-- BAD: No mode - buttons overlap during transition! -->
  <Transition name="fade">
    <button v-if="isEditing" key="save" @click="save">Save</button>
    <button v-else key="edit" @click="edit">Edit</button>
  </Transition>
</template>

<style>
.fade-enter-active, .fade-leave-active {
  transition: opacity 0.3s;
}
.fade-enter-from, .fade-leave-to {
  opacity: 0;
}
</style>

<!--
Result: Both buttons visible during transition
- Old button fading out
- New button fading in simultaneously
- Layout breaks as both take space
-->

Correct Code:

<template>
  <!-- GOOD: out-in mode ensures sequential animation -->
  <Transition name="fade" mode="out-in">
    <button v-if="isEditing" key="save" @click="save">Save</button>
    <button v-else key="edit" @click="edit">Edit</button>
  </Transition>
</template>

<style>
.fade-enter-active, .fade-leave-active {
  transition: opacity 0.3s;
}
.fade-enter-from, .fade-leave-to {
  opacity: 0;
}
</style>

<!--
Result: Clean sequential animation
1. Edit button fades out completely
2. Save button fades in
No overlap, no layout issues
-->

Transition Modes Explained

No Mode (Default)

Time:     |----- leave animation -----|
          |----- enter animation -----|

Elements are animated simultaneously (parallel)

mode="out-in" (Recommended for most cases)

Time:     |----- leave animation -----|
                                      |----- enter animation -----|

Old element leaves first, then new element enters (sequential)

mode="in-out" (Rare use case)

Time:                                 |----- leave animation -----|
          |----- enter animation -----|

New element enters first, then old element leaves

When to Use Each Mode

Use mode="out-in" for:

• Toggle buttons (Edit/Save, Play/Pause)
• Tab content switching
• Multi-step forms
• State-based content (Loading/Error/Success)
• Any mutually exclusive content

<template>
  <!-- Tab content switching -->
  <Transition name="slide" mode="out-in">
    <component :is="currentTabComponent" :key="currentTab" />
  </Transition>

  <!-- State-based UI -->
  <Transition name="fade" mode="out-in">
    <LoadingSpinner v-if="loading" key="loading" />
    <ErrorMessage v-else-if="error" key="error" :message="error" />
    <DataDisplay v-else key="data" :data="data" />
  </Transition>
</template>

Use mode="in-out" for:

• Card flip effects where new content appears behind old
• Specific design requirements where overlap is intentional
• Rarely used in practice

<template>
  <!-- Card flip effect - new card slides in behind -->
  <Transition name="flip" mode="in-out">
    <div :key="cardId" class="card">{{ cardContent }}</div>
  </Transition>
</template>

Use No Mode for:

• Cross-fade effects where overlap is desired
• Image galleries with smooth blending
• Background transitions

<template>
  <!-- Image cross-fade - overlap creates smooth blend -->
  <Transition name="crossfade">
    <img :key="currentImage" :src="currentImage" class="gallery-image" />
  </Transition>
</template>

<style>
.gallery-image {
  position: absolute; /* Stack images on top of each other */
}

.crossfade-enter-active,
.crossfade-leave-active {
  transition: opacity 0.5s;
}

.crossfade-enter-from,
.crossfade-leave-to {
  opacity: 0;
}
</style>

Handling Absolute Positioning

If you must use the default mode (no mode) for non-overlapping elements, use absolute positioning:

<template>
  <div class="container">
    <Transition name="slide">
      <div v-if="showA" key="a" class="panel">Panel A</div>
      <div v-else key="b" class="panel">Panel B</div>
    </Transition>
  </div>
</template>

<style>
.container {
  position: relative;
  height: 200px; /* Fixed height needed */
}

.panel {
  position: absolute;
  width: 100%;
}

.slide-enter-active,
.slide-leave-active {
  transition: transform 0.3s, opacity 0.3s;
}

.slide-enter-from {
  transform: translateX(100%);
  opacity: 0;
}

.slide-leave-to {
  transform: translateX(-100%);
  opacity: 0;
}
</style>

Reference

• Vue.js Transition Modes