1---
2title: Template Ref Array Order Not Guaranteed in v-for
3impact: MEDIUM
4impactDescription: Refs collected from v-for may not match source array order, causing index-based bugs
5type: gotcha
6tags: [vue3, template-refs, v-for, arrays, ordering]
7---
8 
9# Template Ref Array Order Not Guaranteed in v-for
10 
11**Impact: MEDIUM** - When using template refs inside `v-for`, Vue collects the element references into an array. However, this array does NOT guarantee the same order as the source array. Relying on index-based access can lead to subtle bugs.
12 
13This caveat is not obvious and can cause hard-to-debug issues when you assume the ref array matches your data order.
14 
15> **Warning: `useTemplateRef()` does NOT work with v-for refs in Vue 3.5**
16>
17> The `useTemplateRef()` API returns `null` when used with refs inside `v-for`. This is a known limitation. You must use the legacy pattern with `ref()` and a matching template ref name:
18>
19> ```ts
20> // Does NOT work with v-for - returns null
21> const itemRefs = useTemplateRef('items')
22>
23> // Works with v-for - use this pattern instead
24> const items = ref([])  // name must match ref="items" in template
25> ```
26>
27> The examples in this rule show `useTemplateRef()` for illustration, but in practice you should use the legacy `ref()` pattern for v-for scenarios until this limitation is addressed.
28 
29## Task Checklist
30 
31- [ ] Never assume ref array indices match source data array indices
32- [ ] Use data attributes or other identifiers to correlate refs with data
33- [ ] Consider function refs for complex scenarios requiring ordered access
34- [ ] Test with dynamic list operations (add, remove, reorder) to verify behavior
35 
36**Incorrect:**
37```vue
38<script setup>
39import { ref, useTemplateRef, onMounted } from 'vue'
40 
41const items = ref(['First', 'Second', 'Third'])
42const itemRefs = useTemplateRef('items')
43 
44onMounted(() => {
45  // WRONG: Assuming itemRefs[0] corresponds to items[0]
46  // The order is NOT guaranteed to match!
47  items.value.forEach((item, index) => {
48    console.log(`${item}: `, itemRefs.value[index]) // May be wrong element!
49  })
50})
51</script>
52 
53<template>
54  <ul>
55    <li v-for="item in items" ref="items" :key="item">
56      {{ item }}
57    </li>
58  </ul>
59</template>
60```
61 
62**Correct:**
63```vue
64<script setup>
65import { ref, useTemplateRef, onMounted } from 'vue'
66 
67const items = ref([
68  { id: 1, text: 'First' },
69  { id: 2, text: 'Second' },
70  { id: 3, text: 'Third' }
71])
72const itemRefs = useTemplateRef('items')
73 
74onMounted(() => {
75  // CORRECT: Use data attributes to identify elements
76  itemRefs.value.forEach(el => {
77    const id = el.dataset.id
78    const item = items.value.find(i => i.id === Number(id))
79    console.log(`${item.text}: `, el)
80  })
81})
82</script>
83 
84<template>
85  <ul>
86    <li
87      v-for="item in items"
88      ref="items"
89      :key="item.id"
90      :data-id="item.id"
91    >
92      {{ item.text }}
93    </li>
94  </ul>
95</template>
96```
97 
98```vue
99<script setup>
100import { ref, onMounted, onBeforeUpdate } from 'vue'
101 
102const items = ref(['First', 'Second', 'Third'])
103const itemRefs = ref(new Map())
104 
105// CORRECT: Use function refs for precise control
106function setItemRef(el, item) {
107  if (el) {
108    itemRefs.value.set(item, el)
109  } else {
110    itemRefs.value.delete(item)
111  }
112}
113 
114// Reset before each update to handle removed items
115onBeforeUpdate(() => {
116  itemRefs.value.clear()
117})
118 
119onMounted(() => {
120  // Access refs by their associated data item
121  items.value.forEach(item => {
122    const el = itemRefs.value.get(item)
123    console.log(`${item}: `, el)
124  })
125})
126</script>
127 
128<template>
129  <ul>
130    <li
131      v-for="item in items"
132      :key="item"
133      :ref="(el) => setItemRef(el, item)"
134    >
135      {{ item }}
136    </li>
137  </ul>
138</template>
139```
140 
141```vue
142<script setup>
143import { ref, useTemplateRef, onMounted } from 'vue'
144 
145const items = ref(['First', 'Second', 'Third'])
146const itemRefs = useTemplateRef('items')
147 
148// CORRECT: If order matters, sort refs by DOM position
149onMounted(() => {
150  const sortedRefs = [...itemRefs.value].sort((a, b) => {
151    // Sort by DOM order using compareDocumentPosition
152    return a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1
153  })
154 
155  // Now sortedRefs matches visual/DOM order
156  sortedRefs.forEach((el, index) => {
157    console.log(`Position ${index}: `, el.textContent)
158  })
159})
160</script>
161 
162<template>
163  <ul>
164    <li v-for="item in items" ref="items" :key="item">
165      {{ item }}
166    </li>
167  </ul>
168</template>
169```
170 
171## Reference
172- [Vue.js Template Refs - Refs inside v-for](https://vuejs.org/guide/essentials/template-refs.html#refs-inside-v-for)
173