Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 87 ยท Lifecycle and Composition API

TransitionGroup and List Animation

Animate items entering, leaving and changing position in a v-for list with Vue's TransitionGroup, including move transitions, staggered delays and key rules.

The Transition component animates one element or component that appears and disappears. Real interfaces are full of lists: todo items that slide in, search results that fade out when you type, cards that glide to a new position when you sort them. A single <Transition> cannot do that, because it wraps exactly one child. For lists, Vue provides <TransitionGroup>.

<TransitionGroup> wraps a v-for list (see List Rendering) and applies enter and leave animations to every item as it is added or removed. It also does something <Transition> cannot: it animates items that stay but change position, so a sorted or shuffled list slides smoothly instead of jumping.

How TransitionGroup differs from Transition

Most of what you know about <Transition> carries over: the same CSS classes (v-enter-from, v-enter-active, v-leave-to and so on), the same name prop, the same JavaScript hooks. The differences are the part to learn:

  • By default <TransitionGroup> renders no wrapper element. Pass tag="ul" (or any element or component) if you want one.
  • It does not support the mode prop (out-in), because items enter and leave side by side rather than swapping one for another.
  • The transition classes are applied to each child, never to the container.
  • Every child must have a unique key.
  • It adds a fourth class, -move, which is applied while an item slides to a new position.
flowchart TD
  A["Reactive list changes<br/>(add, remove, reorder)"] --> B["Vue compares keys<br/>with the previous render"]
  B --> C["New key"]
  B --> D["Missing key"]
  B --> E["Same key, new position"]
  C --> F["Enter classes on the item"]
  D --> G["Leave classes on the item"]
  E --> H["Move class on the item"]

TransitionGroup decides which animation each item gets by comparing keys, not positions.

Enter, leave and move

Here is a complete example. Each button changes the list in a different way, and every change is animated.

Adding, removing and reordering with a move transition

Press Reverse and watch: no item is added or removed, yet every row slides to its new place. Press Add at position 3 and the new row fades in from the right while the rows below it slide down to make room. Click a row and it fades out while the rows below close the gap.

Three pieces of CSS make this work:

  1. .list-enter-from and .list-leave-to describe the hidden state: transparent and shifted to the right.
  2. .list-enter-active, .list-leave-active and .list-move carry the actual transition. Putting the same rule on all three keeps things short.
  3. .list-leave-active { position: absolute } takes a leaving item out of the layout flow. Without it, the leaving row would keep occupying its space until it finished fading, and the rows below would only start moving afterwards, which looks jerky. The container needs position: relative so the absolutely positioned row stays inside it, and left: 0; right: 0 keeps it as wide as it was.

How the move animation works

Vue uses a technique called FLIP (First, Last, Invert, Play). Before the DOM updates it records where every item is. After the update it records where every item ended up, then applies a transform that moves each item back to where it started and, one frame later, adds the -move class so the transform eases to zero. The browser animates only transform, which is cheap.

This has two practical consequences:

  • The -move class must define a transition on transform (or on all, as above).
  • Items must be able to be transformed. Elements with display: inline cannot, so use block, inline-block, flex or grid items. A plain <li> or <div> is fine. A bare <span> is not.

If you do not use a name, the default class names start with v-: v-move, v-enter-active, and so on. You can also set a custom class for the move step with the move-class prop, which is handy when you share one animation across several lists.

Keys are not optional

<TransitionGroup> figures out what happened by matching keys between the old and new render. That is why every child needs a unique, stable key, and why the key should come from the data (an id), never from the loop index.

Try to picture what goes wrong with :key="index". If you remove the first item of a five-item list, the old keys were 0, 1, 2, 3, 4 and the new ones are 0, 1, 2, 3. Vue concludes that the item with key 4 left, and that the items with keys 0 to 3 stayed but changed text. The result is the last row fading out, no sliding, and content that appears to rewrite itself. With :key="item.id", the removed item itself leaves and the others slide up. Stable keys are the same rule you learned in List Rendering; animation just makes a mistake visible.

Without keys, Vue warns in the console during development and the animations are unreliable. Never use Math.random() for keys either: a new key on every render means every item looks new, so every item leaves and enters again.

Staggered lists

A whole list animating at the same instant feels mechanical. A stagger delays each item slightly more than the previous one, so the list ripples in. You can do this in pure CSS by giving every item its position as a CSS custom property and multiplying it by a delay.

Staggered enter with a filter box

When the page loads, the appear prop makes the initial items play the enter animation too, and the CSS variable --i turns into a growing delay: the first row starts immediately, the second after 70 ms, the third after 140 ms. Type an into the box. Items that no longer match fade out, those that remain slide up to close the gaps, and nothing new needs to enter.

The delay is only on -enter-active. If you also put it on -leave-active, rows would linger before leaving, and if you put it on -move, the whole list would visibly lag.

Staggering with JavaScript hooks

When the delay depends on something CSS cannot express, use the JavaScript hooks. <TransitionGroup> accepts the same hooks as <Transition>: @before-enter, @enter, @leave, and so on. Set :css="false" so Vue skips class detection and waits for your done callback. A typical pattern passes the item's index through a data-index attribute:

HTML
<transition-group tag="ul" :css="false" @before-enter="onBeforeEnter" @enter="onEnter">
  <li v-for="(item, index) in items" :key="item.id" :data-index="index">{{ item.label }}</li>
</transition-group>
JavaScript
function onBeforeEnter(el) {
  el.style.opacity = 0;
  el.style.transform = "translateY(-10px)";
}

function onEnter(el, done) {
  const delay = Number(el.dataset.index) * 80;
  setTimeout(() => {
    el.style.transition = "all 0.3s ease";
    el.style.opacity = 1;
    el.style.transform = "";
    setTimeout(done, 300);
  }, delay);
}

This is the same idea as the CSS version, written by hand. Prefer CSS whenever it can express the effect: it is shorter and runs off the main thread. Reach for hooks when you integrate an animation library or compute timings from data.

Practical tips

  • Animate transform and opacity. They are cheap for the browser. Animating height or margin forces layout on every frame, which gets slow in long lists.
  • Do not animate huge lists. Hundreds of simultaneous move transitions can drop frames. Animate a page of items, or only the items that change.
  • Wrap with tag when you need a container. With no tag, the children become direct children of whatever contains the <TransitionGroup>, which is perfect inside a flex or grid parent.
  • Mind prefers-reduced-motion. Some people get dizzy from sliding motion. Wrap your transition rules in @media (prefers-reduced-motion: no-preference) or shorten the duration for those users. See Accessibility in Vue.
  • A v-if toggle on the whole list needs <Transition>, not <TransitionGroup>: the group handles items inside a list, a plain <Transition> handles the list appearing at all.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which prop does TransitionGroup NOT support, but Transition does?

    Items in a group enter and leave side by side, so there is no 'wait for the old one to leave first' step. The mode prop (out-in, in-out) only makes sense for a single swapped element.
  2. 2. What is :key="index" likely to cause in an animated list when you delete the first item?

    With index keys, Vue sees keys 0 to 3 as unchanged and key 4 as removed. The wrong row animates out and the others just change content. Keys must come from stable data such as an id.
  3. 3. Why does the leaving item get position: absolute in the examples?

    A leaving element normally keeps its space until its transition ends. Removing it from the flow lets the rest of the list slide up right away, so the move animation runs at the same time as the fade.
  4. 4. Which element is a bad candidate for a move transition?

    Move transitions use CSS transform, which does not apply to inline elements. Use a block, inline-block, flex or grid item.

Summary

  • <TransitionGroup> animates a v-for list: items entering, leaving and moving.
  • It renders no wrapper unless you pass tag, ignores mode, and applies classes to each child.
  • Every child needs a unique, stable key from your data, not the index.
  • The -move class (or move-class) animates items that change position, using FLIP and transform.
  • Use position: absolute on -leave-active so the rest of the list closes the gap at once.
  • Create a stagger with a CSS variable such as --i and transition-delay: calc(var(--i) * 70ms), or with JavaScript hooks and data-index.

Next, move from animating lists to moving between screens: Routing Concepts.