agent-skills/skills/vue-best-practices/reference/transition-nested-duration.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
Specify Explicit Duration for Nested Transitions	MEDIUM	Nested transitions with different timings may end prematurely when Vue detects only the root element's transition end	gotcha	vue3 transition animation duration nested timing

Specify Explicit Duration for Nested Transitions

Impact: MEDIUM - When transitioning elements that contain nested child elements with different animation timings, Vue by default listens only for the first transitionend or animationend event on the root transition element. This means if inner elements have longer or delayed animations, they may be cut off when the root element's transition completes.

Task Checklist

• Identify if your transition contains nested elements with different animation durations
• Use the :duration prop to specify the total time Vue should wait
• Consider using separate enter and leave durations if they differ
• Test animations to ensure nested elements complete fully

Problematic Code:

<template>
  <!-- BAD: Inner element has longer animation that gets cut off -->
  <Transition name="nested">
    <div v-if="show" class="outer">
      <div class="inner">Hello</div>
    </div>
  </Transition>
</template>

<style>
.nested-enter-active .outer,
.nested-leave-active .outer {
  transition: opacity 0.3s ease;
}

.nested-enter-active .inner,
.nested-leave-active .inner {
  /* This 0.5s animation gets cut off at 0.3s when outer finishes! */
  transition: transform 0.5s ease 0.2s; /* 0.2s delay + 0.5s = 0.7s total */
}

.nested-enter-from .outer,
.nested-leave-to .outer {
  opacity: 0;
}

.nested-enter-from .inner,
.nested-leave-to .inner {
  transform: translateX(-30px);
}
</style>

Correct Code:

<template>
  <!-- GOOD: Explicit duration ensures all nested animations complete -->
  <Transition name="nested" :duration="700">
    <div v-if="show" class="outer">
      <div class="inner">Hello</div>
    </div>
  </Transition>
</template>

<style>
.nested-enter-active .outer,
.nested-leave-active .outer {
  transition: opacity 0.3s ease;
}

.nested-enter-active .inner,
.nested-leave-active .inner {
  /* Now this animation completes fully */
  transition: transform 0.5s ease 0.2s;
}

.nested-enter-from .outer,
.nested-leave-to .outer {
  opacity: 0;
}

.nested-enter-from .inner,
.nested-leave-to .inner {
  transform: translateX(-30px);
}
</style>

Different Enter and Leave Durations

<template>
  <!-- GOOD: Separate durations for enter and leave -->
  <Transition
    name="complex"
    :duration="{ enter: 500, leave: 800 }"
  >
    <div v-if="show" class="container">
      <h1 class="title">Title</h1>
      <p class="content">Content with staggered animation</p>
    </div>
  </Transition>
</template>

<style>
/* Enter: title first, then content */
.complex-enter-active .title {
  transition: opacity 0.3s ease, transform 0.3s ease;
}

.complex-enter-active .content {
  transition: opacity 0.3s ease 0.2s, transform 0.3s ease 0.2s;
}

/* Leave: content first, then title (reverse order) */
.complex-leave-active .content {
  transition: opacity 0.3s ease, transform 0.3s ease;
}

.complex-leave-active .title {
  transition: opacity 0.5s ease 0.3s, transform 0.5s ease 0.3s;
}

.complex-enter-from .title,
.complex-enter-from .content,
.complex-leave-to .title,
.complex-leave-to .content {
  opacity: 0;
  transform: translateY(20px);
}
</style>

Choreographed Staggered Animations

<template>
  <Transition name="stagger" :duration="800">
    <div v-if="show" class="card">
      <img class="card-image" src="..." />
      <h2 class="card-title">Title</h2>
      <p class="card-body">Body text...</p>
      <button class="card-action">Action</button>
    </div>
  </Transition>
</template>

<style>
/* Staggered entrance: image -> title -> body -> action */
.stagger-enter-active .card-image { transition: all 0.3s ease; }
.stagger-enter-active .card-title { transition: all 0.3s ease 0.1s; }
.stagger-enter-active .card-body { transition: all 0.3s ease 0.2s; }
.stagger-enter-active .card-action { transition: all 0.3s ease 0.3s; }
/* Total: 0.3s delay + 0.3s animation = 0.6s, but use 800ms for safety */

.stagger-enter-from .card-image,
.stagger-enter-from .card-title,
.stagger-enter-from .card-body,
.stagger-enter-from .card-action {
  opacity: 0;
  transform: translateY(10px);
}
</style>

Calculating Duration

Use this formula to calculate the correct duration:

duration = max(delay + animation_duration) for all nested elements

Example:

• Element A: no delay, 300ms duration = 300ms total
• Element B: 100ms delay, 300ms duration = 400ms total
• Element C: 200ms delay, 500ms duration = 700ms total

Required :duration: 700 (or slightly higher for safety margin)

Reference

• Vue.js Transition - Nested Transitions