Crisis de identidad

Cuando los elementos de una lista cambian — se reordenan, agregan o eliminan — Svelte necesita saber qué elementos del DOM corresponden a qué datos. Sin una identificación adecuada, las actualizaciones pueden comportarse de manera inesperada. Las claves resuelven esto.

Lo que aprenderás

Por qué las listas sin clave pueden causar problemas
Cómo agregar claves a los bloques each
Cuándo importan más las claves

El problema sin claves

Considera una lista donde los elementos pueden eliminarse:

<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>

Prueba esto: escribe algo en el primer input, luego haz clic en "Remove First." ¿Qué sucede?

Sin claves, Svelte hace la correspondencia por posición. Cuando eliminas el primer elemento:

El primer elemento del DOM permanece, pero ahora muestra los datos del que era el segundo elemento
El valor escrito en el input permanece en el primer elemento
El resultado: datos incorrectos en el lugar equivocado

Agregando claves

Las claves le indican a Svelte cómo identificar cada elemento de manera única:

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

El (service.id) al final es la expresión de clave. Ahora cuando eliminas el primer elemento:

Svelte sabe qué elemento del DOM pertenece a qué servicio
El elemento correcto es eliminado
Los valores de los inputs permanecen con sus elementos correspondientes

Requisitos de las claves

Las claves deben ser:

Únicas — Cada elemento de la lista necesita un valor de clave diferente:

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

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

Estables — El mismo elemento siempre debe tener la misma clave:

<!-- ❌ 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 — Las claves deben ser cadenas de texto o 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)}

Cuándo importan más las claves

Las claves son esenciales cuando:

Los elementos pueden reordenarse:

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

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

Los elementos pueden eliminarse:

<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}

Los elementos contienen inputs de formulario:

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

Los elementos tienen animaciones:

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

Servicios de BookIt con claves

Actualiza la página de servicios para usar claves:

<!-- 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 cambian, las claves son técnicamente opcionales. Pero agregarlas es una buena práctica — nunca sabes cuándo una lista puede volverse dinámica.

El índice como clave: cuándo está bien usarlo

Usar el índice como clave es aceptable cuando:

La lista es estática (nunca cambia)
Los elementos nunca se reordenan
Los elementos solo se agregan al final

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

Pero prefiere IDs propios cuando estén disponibles. Son más robustos.

Generando IDs

Si tus datos no tienen IDs, puedes generarlos:

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

O usa una librería como uuid para IDs globalmente únicos:

import { v4 as uuidv4 } from 'uuid';

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

Errores comunes

Usar claves no únicas

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

Svelte advertirá sobre claves duplicadas. Cada elemento debe tener una clave distinta.

Usar el Índice para Listas Dinámicas

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

Después de eliminar un elemento, todos los índices se desplazan, causando actualizaciones incorrectas.

Olvidar las Keys por Completo

En demos simples, olvidar las keys puede no causar problemas visibles. Pero cuando agregas interactividad, animaciones o inputs de formulario, los problemas aparecen. Agrega keys desde el principio.

Resumen

Las keys ayudan a Svelte a rastrear qué elementos del DOM pertenecen a qué elementos de datos. Usa identificadores únicos y estables — típicamente un campo id. Esto garantiza un comportamiento correcto cuando las listas se filtran, ordenan o modifican.

Conclusiones clave:

Agrega keys con {#each items as item (item.id)}
Las keys deben ser únicas y estables
Siempre usa keys para listas dinámicas e interactivas

Próximos Pasos

Puedes renderizar listas y mostrar/ocultar contenido. Ahora combinémoslos. Continúa con Filtrar Servicios por Categoría para construir displays filtrados interactivos.