1---
2title: TransitionGroup No Longer Renders Default Wrapper Element in Vue 3
3impact: MEDIUM
4impactDescription: Vue 2 to Vue 3 migration may break layouts relying on the default span wrapper
5type: gotcha
6tags: [vue3, transition-group, migration, vue2, breaking-change, wrapper-element]
7---
8 
9# TransitionGroup No Longer Renders Default Wrapper Element in Vue 3
10 
11**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.
12 
13If your code relies on the wrapper element for styling or layout, you must explicitly specify the `tag` prop in Vue 3.
14 
15## Task Checklist
16 
17- [ ] When migrating from Vue 2, add explicit `tag` prop to all `<TransitionGroup>` components
18- [ ] Review CSS selectors that targeted the wrapper element
19- [ ] Update parent component styles that expected a wrapper element
20- [ ] Consider if the wrapper element is actually needed in Vue 3
21 
22**Vue 2 Behavior (wrapper element by default):**
23```vue
24<template>
25  <transition-group name="list">
26    <div v-for="item in items" :key="item.id">{{ item }}</div>
27  </transition-group>
28</template>
29 
30<!-- Renders as: -->
31<span>  <!-- Default wrapper in Vue 2 -->
32  <div>Item 1</div>
33  <div>Item 2</div>
34</span>
35```
36 
37**Vue 3 Behavior (no wrapper by default):**
38```vue
39<template>
40  <TransitionGroup name="list">
41    <div v-for="item in items" :key="item.id">{{ item }}</div>
42  </TransitionGroup>
43</template>
44 
45<!-- Renders as (fragment): -->
46<div>Item 1</div>
47<div>Item 2</div>
48<!-- No wrapper element! -->
49```
50 
51**Vue 3 - Explicitly specify wrapper:**
52```vue
53<template>
54  <!-- Use tag prop to specify wrapper element -->
55  <TransitionGroup name="list" tag="ul">
56    <li v-for="item in items" :key="item.id">{{ item }}</li>
57  </TransitionGroup>
58</template>
59 
60<!-- Renders as: -->
61<ul>
62  <li>Item 1</li>
63  <li>Item 2</li>
64</ul>
65```
66 
67## Migration Scenarios
68 
69### Layout Depending on Wrapper
70 
71**Vue 2 code that breaks in Vue 3:**
72```vue
73<template>
74  <transition-group class="grid-container" name="list">
75    <div v-for="item in items" :key="item.id">{{ item }}</div>
76  </transition-group>
77</template>
78 
79<style>
80.grid-container {
81  display: grid;
82  grid-template-columns: repeat(3, 1fr);
83}
84</style>
85```
86 
87In Vue 3, the class is not applied to anything because there's no wrapper element.
88 
89**Fixed for Vue 3:**
90```vue
91<template>
92  <TransitionGroup class="grid-container" name="list" tag="div">
93    <div v-for="item in items" :key="item.id">{{ item }}</div>
94  </TransitionGroup>
95</template>
96```
97 
98### Semantic HTML Lists
99 
100**Vue 2:**
101```vue
102<transition-group tag="ul" name="list">
103  <li v-for="item in items" :key="item.id">{{ item }}</li>
104</transition-group>
105```
106 
107**Vue 3 (same syntax, but now tag is more important):**
108```vue
109<TransitionGroup tag="ul" name="list">
110  <li v-for="item in items" :key="item.id">{{ item }}</li>
111</TransitionGroup>
112```
113 
114### When You Don't Need a Wrapper
115 
116Vue 3's fragment support means you might not need a wrapper at all:
117 
118```vue
119<template>
120  <div class="parent-with-styles">
121    <!-- No tag needed if parent handles layout -->
122    <TransitionGroup name="fade">
123      <span v-for="item in items" :key="item.id">{{ item }}</span>
124    </TransitionGroup>
125  </div>
126</template>
127 
128<style>
129.parent-with-styles {
130  display: flex;
131  gap: 8px;
132}
133</style>
134```
135 
136## In-DOM Template Syntax
137 
138When using in-DOM templates (not SFCs), remember to use kebab-case:
139 
140```html
141<!-- In-DOM template -->
142<transition-group tag="ul" name="list">
143  <li v-for="item in items" :key="item.id">{{ item }}</li>
144</transition-group>
145 
146<!-- NOT -->
147<TransitionGroup tag="ul" name="list">  <!-- Won't work in DOM templates -->
148```
149 
150## Reference
151- [Vue 3 Migration Guide - TransitionGroup Root Element](https://v3-migration.vuejs.org/breaking-changes/transition-group.html)
152- [Vue.js TransitionGroup](https://vuejs.org/guide/built-ins/transition-group.html)
153