Crise de Identidade

Quando itens em uma lista mudam — reordenados, adicionados, removidos — o Svelte precisa saber quais elementos do DOM correspondem a quais itens de dados. Sem identificação adequada, as atualizações podem se comportar de forma inesperada. As chaves resolvem isso.

O Que Você Aprenderá

Por que listas sem chaves podem causar problemas
Como adicionar chaves a blocos each
Quando as chaves são mais importantes

O Problema Sem Chaves

Considere uma lista onde itens podem ser removidos:

<script>
  let services = $state([
    { id: '1', name: 'Lawn Mowing' },
    { id: '2', name: 'Hedge Trimming' },
    { id: '3', name: 'Tree Pruning' }
  ]);
  
  function removeFirst() {
    services = services.slice(1);
  }
</script>

{#each services as service}
  <div class="service">
    <input value={service.name} />
    <span>{service.name}</span>
  </div>
{/each}

<button onclick={removeFirst}>Remove First</button>

Tente isso: digite algo no primeiro campo, depois clique em "Remove First." O que acontece?

Sem chaves, o Svelte faz a correspondência por posição. Quando você remove o primeiro item:

O primeiro elemento do DOM permanece, mas agora exibe dados do que era o segundo item
O valor digitado no campo permanece no primeiro elemento
O resultado: dados errados no lugar errado

Adicionando Chaves

As chaves informam ao Svelte como identificar cada item de forma única:

{#each services as service (service.id)}
  <div class="service">
    <input value={service.name} />
    <span>{service.name}</span>
  </div>
{/each}

O (service.id) no final é a expressão de chave. Agora, quando você remove o primeiro item:

O Svelte sabe qual elemento do DOM pertence a qual serviço
O elemento correto é removido
Os valores dos campos permanecem com seus itens correspondentes

Requisitos das Chaves

As chaves devem ser:

Únicas — Cada item na lista precisa de um valor de chave diferente:

<!-- ✅ Good: IDs are unique -->
{#each services as service (service.id)}

<!-- ❌ Bad: Multiple items could have same price -->
{#each services as service (service.price)}

Estáveis — O mesmo item deve sempre ter a mesma chave:

<!-- ❌ Bad: Index changes when items are reordered -->
{#each services as service, index (index)}

<!-- ✅ Good: ID stays with the item -->
{#each services as service (service.id)}

Primitivas — As chaves devem ser strings ou números:

<!-- ✅ Good: string key -->
{#each services as service (service.id)}

<!-- ✅ Good: slug as key -->
{#each services as service (service.slug)}

<!-- ❌ Avoid: object as key -->
{#each services as service (service)}

Quando as Chaves São Mais Importantes

As chaves são essenciais quando:

Itens podem ser reordenados:

<script>
  let services = $state([...]);
  
  function sortByPrice() {
    services = [...services].sort((a, b) => a.price - b.price);
  }
</script>

{#each services as service (service.id)}
  <!-- ... -->
{/each}

Itens podem ser removidos:

<script>
  function removeService(id) {
    services = services.filter(s => s.id !== id);
  }
</script>

{#each services as service (service.id)}
  <div>
    {service.name}
    <button onclick={() => removeService(service.id)}>Remove</button>
  </div>
{/each}

Itens contêm campos de formulário:

{#each services as service (service.id)}
  <input bind:value={service.name} />
{/each}

Itens possuem animações:

{#each services as service (service.id)}
  <div transition:slide>
    {service.name}
  </div>
{/each}

Serviços do BookIt com Chaves

Atualize a página de serviços para usar chaves:

<!-- filename: src/routes/services/+page.svelte -->
<script>
  const services = [
    { id: '1', slug: 'lawn-mowing', name: 'Lawn Mowing', price: 50 },
    { id: '2', slug: 'hedge-trimming', name: 'Hedge Trimming', price: 75 },
    { id: '3', slug: 'garden-consultation', name: 'Garden Consultation', price: 100 }
  ];
</script>

<h1>Our Services</h1>

{#each services as service (service.id)}
  <article class="service-card">
    <h2>{service.name}</h2>
    <p>${service.price}</p>
    <a href="/services/{service.slug}">View Details</a>
  </article>
{/each}

Para listas estáticas que nunca mudam, as chaves são tecnicamente opcionais. Mas adicioná-las é uma boa prática — você nunca sabe quando uma lista pode se tornar dinâmica.

Índice como Chave: Quando É Aceitável

Usar o índice como chave é aceitável quando:

A lista é estática (nunca muda)
Os itens nunca são reordenados
Os itens são adicionados apenas ao final

<!-- OK for a static, append-only list -->
{#each logMessages as message, index (index)}
  <p>{message}</p>
{/each}

Mas prefira IDs adequados quando disponíveis. Eles são mais robustos.

Gerando IDs

Se seus dados não possuem IDs, você pode gerá-los:

<script>
  let nextId = 1;
  
  let items = $state([]);
  
  function addItem(name) {
    items = [...items, { id: nextId++, name }];
  }
</script>

Ou use uma biblioteca como uuid para IDs globalmente únicos:

import { v4 as uuidv4 } from 'uuid';

const newItem = { id: uuidv4(), name: 'New Service' };

Erros Comuns

Usando Chaves Não Únicas

<!-- ❌ Category isn't unique — multiple items share it -->
{#each services as service (service.category)}

O Svelte irá alertar sobre chaves duplicadas. Cada item deve ter uma chave distinta.

Usando Índice para Listas Dinâmicas

<!-- ❌ Index changes when items are removed -->
{#each services as service, i (i)}
  <button onclick={() => remove(i)}>Remove</button>
{/each}

Após a remoção, todos os índices mudam, causando atualizações incorretas.

Esquecer as Keys Completamente

Para demonstrações simples, esquecer as keys pode não causar problemas visíveis. Mas quando você adiciona interatividade, animações ou entradas de formulário, os problemas surgem. Adicione keys desde o início.

Resumo

As keys ajudam o Svelte a rastrear quais elementos do DOM pertencem a quais itens de dados. Use identificadores únicos e estáveis — tipicamente um campo id. Isso garante o comportamento correto quando as listas são filtradas, ordenadas ou modificadas.

Principais conclusões:

Adicione keys com {#each items as item (item.id)}
As keys devem ser únicas e estáveis
Sempre use keys para listas dinâmicas e interativas

Próximos Passos

Você pode renderizar listas e mostrar/ocultar conteúdo. Agora vamos combiná-los. Continue com Filtrar Serviços por Categoria para criar exibições filtradas interativas.