Animating Lists with TransitionGroup

Your task list animates correctly when items are added or deleted — the row fades in, the removed row fades out — but the moment you shuffle the array, every row that changed position teleports to its new spot. No slide, just a jump. The cause is structural: <Transition> wraps one element, while a reorder changes the position of many existing elements, so you need <TransitionGroup>, which applies enter, leave, and move transitions to each child of a v-for individually.

<TransitionGroup name="list" tag="ul" class="todo-list">
  <li v-for="task in tasks" :key="task.id" class="todo-row">
    {{ task.title }}
  </li>
</TransitionGroup>

The tag prop decides the wrapper element rendered around the children (ul here; without tag the group renders as a fragment with no wrapper at all). Enter and leave classes apply to the individual li children, never to the container — a common misread when the wrapper seems unanimated.

Adding fade-in/fade-out CSS is not enough for reorders. That needs the move class, and the mechanism behind it is the FLIP technique — First, Last, Invert, Play:

1. First — before the patch, TransitionGroup records each child's viewport position (getBoundingClientRect) keyed by its vnode.
2. Last — the DOM updates to the new order; the children are already at their final coordinates.
3. Invert — for every child whose position changed, Vue writes an inline transform: translate(dx, dy) that carries it back to where it was, with transition-duration: 0s so nothing animates yet, then forces a reflow so the inverted position is painted.
4. Play — the move class (list-move for name="list", or whatever you pass to move-class) is added and the inline transform is cleared; the browser now transitions from the inverted position to the natural one. Vue removes the move class on the transitionend of transform.

.list-enter-active,
.list-leave-active,
.list-move {
  transition: all 0.5s ease;
}
.list-enter-from,
.list-leave-to {
  opacity: 0;
  transform: translateX(30px);
}
/* leaving items leave the flow so moving rows are measured correctly */
.list-leave-active {
  position: absolute;
}

Two lines in that block carry the weight. position: absolute on -leave-active takes the outgoing row out of layout while it fades, so the rows that slide up are computed against the final geometry rather than against a corpse occupying space. And transition must mention transform on the move class — more on why that is not optional in the next chapter's failure catalogue.

Insertions and moves also combine inside one update: while the new row fades in at its slot, the rows below slide down at the same time, because the enter runs on the inserted node while the FLIP pass runs on the surviving ones — and since positions are re-measured after the patch, the sliding rows are already at final coordinates and only the entering row's opacity is in flight. Nested groups work too: when a parent group's rows are themselves moving, Vue compensates for the parent's displacement while measuring the child group's rows, so a list inside a list does not double-animate.

In an interview, the sentence that separates candidates is this: enter and leave handle membership changes, while the move class plus FLIP handles reordering — and all three need the same unique keys to know which DOM node belongs to which data item, which is where the next failure mode lives.

TransitionGroup is strict about one thing: every child must carry a unique key. Forget it and the dev console tells you plainly — <TransitionGroup> children must be keyed. — but the subtler mistake passes the lint check: :key="index" from the v-for. It works, and it quietly disables most of what you installed the component for.

Watch what the diff does with index keys when a new task is inserted at the top of a five-row list. Before: keys [0,1,2,3,4]. After: the new row takes key 0, and every existing row's key shifts by one. The reconciler compares children position by position, and position 0's old vnode and new vnode share both type and key — so do positions 1 through 4. Vue patches the text in place on five existing DOM nodes and appends one new node at the bottom. No node ever moves, so the FLIP pass measures no position change and no move transition runs. The insertion animation plays on the last row, not the first, and any row-local state — a focused input, a checked box, an open dropdown — stays glued to the position instead of travelling with the task.

With :key="task.id" the same insert is one new vnode among five keyed survivors. The reconciler inserts the new node at the top, every other row keeps its own DOM node, their positions genuinely shift, and the move class slides them down while the new row fades in at the top. That is the whole reason the keys are mandatory: key identity is how Vue decides a row is the same row in a new place rather than new content in an old slot.

<!-- correct: node identity follows the data item -->
<li v-for="task in tasks" :key="task.id"> ... </li>

<!-- broken: node identity follows the array position -->
<li v-for="(task, index) in tasks" :key="index"> ... </li>

Two more key rules round out the contract. Keys must be unique within the list — duplicated ids make Vue patch an arbitrary match and animate the wrong row, so derive keys from something genuinely distinct (database id, SKU) rather than a display label that users can make collide. And don't recycle keys across different item types in the same list (task.id and user.id values sharing a keyspace); a collision between an old leaving row and a new entering row forces an early removal of the leaver mid-animation.

Key discipline also decides which row's enter and leave classes fire. With id keys, deleting the third of five tasks runs the leave on that task's own row — the one the user was looking at — and the rows below slide up to close the gap. With index keys, the same deletion removes whichever row occupies the last position: the fade plays at the wrong end of the list, while the surviving rows silently repatch their text to the tasks that followed. The data ends up correct either way; what the user watches during the transition does not. That is also why id keys matter for lists with inputs: the DOM node — and with it focus and draft text — stays attached to the item being edited instead of drifting to whatever now occupies that position.

The diagnostic is quick to run: shuffle your list with index keys and watch the DOM in devtools. If the same element nodes stay put while their text updates, your keys describe positions, and no amount of CSS will produce a slide. Fix the key first, then judge the motion — the class-name contract and its silent failures come next in JavaScript Transition Hooks.

A TransitionGroup list with correct keys still sometimes refuses to slide. The move machinery has real preconditions, and Vue checks one of them before doing any work: it probes whether an element with only the move class applied has a CSS transition on transform (it clones a child, strips the other transition classes, adds the move class, and inspects the computed transition). If the move class does not declare a transition whose property list includes transform — or all, which includes it — Vue skips the entire FLIP pass. The failure is silent: no warning, no console output, rows just teleport.

The full catalogue of ways the slide dies, in the order worth checking:

1. Move class has no transform transition. transition: opacity 0.4s on .list-move animates nothing, because position changes are carried by transform. It must mention transform or all, with a nonzero duration.
2. Animating top, left, or margin instead. These are layout properties: every frame the browser recomputes geometry for the whole list, which turns a 30-row shuffle into visible jank. FLIP exists precisely so the expensive part happens once and the animation rides the compositor.
3. Leaving rows still in flow. Without position: absolute on .list-leave-active, the outgoing row occupies space while it fades, so rows measured for their slide are computed against the wrong layout and stop short or overshoot their slots.
4. A renamed move class that nothing targets. move-class="reorder" applies reorder and nothing else — the generated name-move class is fully replaced, so your .list-move CSS never matches.
5. Expecting a mode to fix the timing. <TransitionGroup> does not accept mode — the prop is not declared, because rows animate independently and there is no single in/out pair to serialize. That distinction from Transition Modes and appear is a favorite interview question.

Then there is cost. FLIP takes a getBoundingClientRect reading of every child before and after each update — O(n) layout reads per patch. At ten rows nobody notices; at a few hundred rows updating every few seconds (live feeds, trading tables, chat logs) the measurements alone compete with your render budget, and if rows also enter and leave with staggered JavaScript timelines the frame budget collapses. Mitigations that hold up: keep moves transform-only, throttle the data source feeding the list, animate only the rows the user can see, and for truly large or virtualized lists drop the per-row choreography entirely — virtualization recycles DOM nodes for different items, which corrupts the position bookkeeping TransitionGroup depends on.

A staggered entrance is the compromise most teams land on — small lists get the full slide, big ones fade rows in on a delay derived from the row index. Wiring that requires JavaScript per row, which is exactly the machinery in JavaScript Transition Hooks.

Sorting is the extreme case of the same tension: reordering thirty rows at once can set all thirty slides in motion simultaneously, each on its own transitionend — technically correct, visually chaotic. The pragmatic fix is a short move duration (250ms) so the shuffle resolves before it becomes the focus, plus the confidence that every moved row's class is cleaned off on its own transitionend; if you want a deliberate, index-staggered sequence instead, that is per-row JavaScript timing again.

Debugging checklist for a dead slide, in one line each: keys unique and data-derived? Move class declares transition: transform? -leave-active absolutely positioned? Positions changing at all (shuffle the data, not the CSS)? Each question localizes the fault to keys, CSS, flow, or data before you start rewriting the component.