agent-skills/skills/vue-best-practices/reference/transition-group-no-default-wrapper-vue3.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
TransitionGroup No Longer Renders Default Wrapper Element in Vue 3	MEDIUM	Vue 2 to Vue 3 migration may break layouts relying on the default span wrapper	gotcha	vue3 transition-group migration vue2 breaking-change wrapper-element

TransitionGroup No Longer Renders Default Wrapper Element in Vue 3

Impact: MEDIUM - In Vue 2, <transition-group> always rendered a wrapper element (default <span>), but in Vue 3, it renders no wrapper element by default thanks to fragment support. This breaking change can cause layout issues and broken styles when migrating from Vue 2.

If your code relies on the wrapper element for styling or layout, you must explicitly specify the tag prop in Vue 3.

Task Checklist

• When migrating from Vue 2, add explicit tag prop to all <TransitionGroup> components
• Review CSS selectors that targeted the wrapper element
• Update parent component styles that expected a wrapper element
• Consider if the wrapper element is actually needed in Vue 3

Vue 2 Behavior (wrapper element by default):

<template>
  <transition-group name="list">
    <div v-for="item in items" :key="item.id">{{ item }}</div>
  </transition-group>
</template>

<!-- Renders as: -->
<span>  <!-- Default wrapper in Vue 2 -->
  <div>Item 1</div>
  <div>Item 2</div>
</span>

Vue 3 Behavior (no wrapper by default):

<template>
  <TransitionGroup name="list">
    <div v-for="item in items" :key="item.id">{{ item }}</div>
  </TransitionGroup>
</template>

<!-- Renders as (fragment): -->
<div>Item 1</div>
<div>Item 2</div>
<!-- No wrapper element! -->

Vue 3 - Explicitly specify wrapper:

<template>
  <!-- Use tag prop to specify wrapper element -->
  <TransitionGroup name="list" tag="ul">
    <li v-for="item in items" :key="item.id">{{ item }}</li>
  </TransitionGroup>
</template>

<!-- Renders as: -->
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>

Migration Scenarios

Layout Depending on Wrapper

Vue 2 code that breaks in Vue 3:

<template>
  <transition-group class="grid-container" name="list">
    <div v-for="item in items" :key="item.id">{{ item }}</div>
  </transition-group>
</template>

<style>
.grid-container {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
}
</style>

In Vue 3, the class is not applied to anything because there's no wrapper element.

Fixed for Vue 3:

<template>
  <TransitionGroup class="grid-container" name="list" tag="div">
    <div v-for="item in items" :key="item.id">{{ item }}</div>
  </TransitionGroup>
</template>

Semantic HTML Lists

Vue 2:

<transition-group tag="ul" name="list">
  <li v-for="item in items" :key="item.id">{{ item }}</li>
</transition-group>

Vue 3 (same syntax, but now tag is more important):

<TransitionGroup tag="ul" name="list">
  <li v-for="item in items" :key="item.id">{{ item }}</li>
</TransitionGroup>

When You Don't Need a Wrapper

Vue 3's fragment support means you might not need a wrapper at all:

<template>
  <div class="parent-with-styles">
    <!-- No tag needed if parent handles layout -->
    <TransitionGroup name="fade">
      <span v-for="item in items" :key="item.id">{{ item }}</span>
    </TransitionGroup>
  </div>
</template>

<style>
.parent-with-styles {
  display: flex;
  gap: 8px;
}
</style>

In-DOM Template Syntax

When using in-DOM templates (not SFCs), remember to use kebab-case:

<!-- In-DOM template -->
<transition-group tag="ul" name="list">
  <li v-for="item in items" :key="item.id">{{ item }}</li>
</transition-group>

<!-- NOT -->
<TransitionGroup tag="ul" name="list">  <!-- Won't work in DOM templates -->

Reference

• Vue 3 Migration Guide - TransitionGroup Root Element
• Vue.js TransitionGroup