v-for renderiza uma lista de elementos iterando sobre um array (ou objeto/intervalo). Você sempre deve emparelhá-lo com uma :key única para que o Vue possa rastrear itens de forma eficiente.
<script setup>
import { ref } from "vue";
const items = ref([{ id: 1, name: "Apple" }, { id: 2, name: "Banana" }]);
</script>
<template>
<ul>
<li v-for="item in items" :key="item.id">{{ item.name }}</li>
</ul>
</template>
<template>
<li v-for="(item, index) in items" :key="item.id">{{ index }}: {{ item.name }}</li>
<li v-for="(value, key) in myObject" :key="key">{{ key }}: {{ value }}</li>
<span v-for="n in 5" :key="n">{{ n }}</span> <!-- range 1..5 -->
</template>
Vue usa o key para identificar quais itens foram alterados, adicionados ou removidos, para que possa reutilizar e reordenar nós DOM existentes em vez de reconstruí-los. Sem uma chave estável, o Vue retorna a uma estratégia "in-place patch" que pode causar bugs:
<!-- ❌ using index as key → wrong when the list reorders/filters -->
<li v-for="(item, i) in items" :key="i">
<input /> <!-- input state can attach to the WRONG item after reordering -->
</li>
<!-- ✅ stable unique id → Vue tracks each item correctly -->
<li v-for="item in items" :key="item.id">...</li>
Usar o índice da matriz como a chave é um erro comum — quando os itens são reordenados, inseridos ou deletados, o estado do componente/DOM (como valores de entrada ou estados de caixas de seleção) pode ficar preso à linha errada.
<!-- ❌ avoid — ambiguous precedence -->
<li v-for="x in items" v-if="x.active">...</li>
<!-- ✅ filter in a computed, or wrap with <template v-for> -->
v-for é como você renderiza listas dinâmicas.
O :key não é opcional na prática: uma chave única e estável permite que o diff virtual DOM do Vue funcione de forma eficiente e evita bugs sutis de incompatibilidade de estado em reordenação/filtragem.
Saber quando usar um id real (nunca o índice para listas dinâmicas) e manter v-for/v-if separados é essencial para listas corretas e com bom desempenho.