x-for mit key: Stabile Listen-Updates in Alpine.js

1. Warum key bei Listen-Updates entscheidend ist

Wenn Alpine.js eine Liste mit x-for rendert und sich die zugrunde liegenden Daten ändern, muss die Bibliothek entscheiden, welche vorhandenen DOM-Elemente wiederverwendet, welche neu erzeugt und welche entfernt werden. Ohne zusätzliche Information verfolgt Alpine dabei standardmäßig die Position in der Liste, nicht die Identität des Datensatzes. Das funktioniert solange gut, wie Einträge nur am Ende hinzugefügt werden, bricht aber sofort, sobald in der Mitte der Liste eingefügt, entfernt oder umsortiert wird.

Der :key-Modifier löst genau dieses Problem, indem er Alpine eine stabile, eindeutige Kennung pro Listeneintrag mitgibt. Mit dieser Kennung kann Alpine ein DOM-Element eindeutig einem Datensatz zuordnen, unabhängig davon, an welcher Position dieser Datensatz gerade steht. Das Ergebnis ist ein korrektes Diffing-Verhalten: Nur tatsächlich neue Einträge erzeugen neue DOM-Elemente, nur tatsächlich entfernte Einträge werden aus dem DOM entfernt, und bestehende Elemente werden bei reiner Umsortierung im DOM verschoben statt neu erzeugt.

In der Praxis betrifft das jede Liste mit veränderlichem Inhalt: Warenkörbe, To-Do-Listen, Kommentar-Threads, Suchergebnisse mit Live-Filterung. Überall dort, wo Einträge nicht nur am Ende angehängt werden, ist :key bei x-for keine Option, sondern eine Notwendigkeit für korrektes Verhalten.

2. Grundsyntax von x-for

Die Grunddirektive x-for wird immer auf ein <template>-Element gesetzt und iteriert über ein Array, das aus dem Alpine-State stammt. Der :key-Modifier wird direkt auf dasselbe <template>-Element gesetzt und erwartet einen eindeutigen Wert pro Iteration, üblicherweise eine ID aus dem Datensatz. Wichtig ist, dass der Key-Ausdruck für jede Iteration einen unterschiedlichen Wert liefern muss, sonst funktioniert die Zuordnung nicht korrekt.

Anders als in manchen anderen Frameworks ist :key bei Alpine.js kein optionales Performance-Feature, sondern ein funktionales Korrektheitsmerkmal. Ohne :key arbeitet x-for trotzdem, aber mit dem Risiko, dass DOM-Elemente ihre Identität verlieren, sobald sich die Reihenfolge der Daten ändert.

// Grundsyntax: x-for mit :key auf demselben template-Element
Alpine.data('todoList', () => ({
  todos: [
    { id: 1, text: 'Angebot erstellen' },
    { id: 2, text: 'Rechnung prüfen' },
    { id: 3, text: 'Kunde anrufen' }
  ]
}));

// <ul x-data="todoList()">
//   <template x-for="todo in todos" :key="todo.id">
//     <li x-text="todo.text"></li>
//   </template>
// </ul>

// todo.id muss für jeden Eintrag eindeutig und über die Zeit stabil sein

3. Probleme ohne key: vertauschter Zustand

Der klassische Bug ohne :key zeigt sich bei Listen mit interaktiven Elementen, etwa Eingabefeldern innerhalb jedes Listeneintrags. Wird ein Eintrag am Anfang der Liste eingefügt, verschiebt Alpine ohne :key nicht die DOM-Elemente entsprechend den Daten, sondern behält die bestehenden DOM-Positionen bei und aktualisiert nur deren Inhalt anhand der neuen Reihenfolge. Ein zuvor in Position 2 fokussiertes Eingabefeld bleibt an Position 2, zeigt aber jetzt Daten eines anderen Eintrags, während der Nutzer weiterhin dort tippt.

Dieses Verhalten betrifft nicht nur Fokus, sondern jeden Zustand, der an ein DOM-Element gebunden ist: Checkbox-Status, Scroll-Position innerhalb eines Eintrags, laufende CSS-Transitions oder Video-Wiedergabepositionen. Ohne :key wird beim Einfügen oder Entfernen in der Mitte der Liste dieser elementgebundene Zustand faktisch zwischen Datensätzen vertauscht, was zu verwirrenden, schwer reproduzierbaren Bugs führt.

// PROBLEM: x-for ohne :key - Zustand wird bei Einfügen falsch zugeordnet
Alpine.data('editableList', () => ({
  items: [
    { id: 1, label: 'Erster Eintrag' },
    { id: 2, label: 'Zweiter Eintrag' }
  ],
  addAtStart() {
    this.items.unshift({ id: Date.now(), label: 'Neuer Eintrag' });
  }
}));

// <template x-for="item in items">  <!-- KEIN :key -->
//   <li>
//     <input type="text" :value="item.label">
//   </li>
// </template>

// Nutzer tippt in Feld von "Erster Eintrag" (Position 1),
// addAtStart() fügt vorne ein -> DOM-Position 1 bleibt fokussiert,
// zeigt aber jetzt Daten des NEUEN Eintrags - Tippzustand vertauscht

4. Der richtige key: stabil und eindeutig

Ein korrekter :key-Wert erfüllt zwei Bedingungen: Er ist innerhalb der Liste eindeutig, und er bleibt für denselben logischen Datensatz über die Zeit stabil, auch wenn sich andere Eigenschaften des Datensatzes ändern. Eine Datenbank-ID oder eine beim Erstellen einmalig generierte UUID sind ideale Kandidaten. Der häufigste Fehler ist die Verwendung des Array-Index als Key, weil sich der Index bei jeder Umsortierung oder jedem Einfügen ändert und damit genau das Problem reproduziert, das :key eigentlich lösen soll.

Mit einer stabilen ID als :key erkennt Alpine korrekt, welche Datensätze neu sind, welche entfernt wurden und welche nur ihre Position gewechselt haben. Für Letzteres verschiebt Alpine das bestehende DOM-Element im DOM-Baum, statt es neu zu erzeugen, wodurch Fokus, Zustand und laufende Animationen korrekt am jeweiligen Datensatz erhalten bleiben, unabhängig von der neuen Position in der Liste.

// LÖSUNG: x-for mit :key auf stabiler, eindeutiger ID
Alpine.data('editableList', () => ({
  items: [
    { id: 1, label: 'Erster Eintrag' },
    { id: 2, label: 'Zweiter Eintrag' }
  ],
  addAtStart() {
    this.items.unshift({ id: crypto.randomUUID(), label: 'Neuer Eintrag' });
  }
}));

// <template x-for="item in items" :key="item.id">
//   <li>
//     <input type="text" :value="item.label">
//   </li>
// </template>

// Jetzt: item.id bleibt stabil, Alpine verschiebt DOM-Elemente korrekt
// statt Inhalte falsch zuzuordnen. Fokus und Tippzustand bleiben am
// richtigen Eintrag, unabhängig von der neuen Position

5. Verschachtelte x-for-Schleifen

Bei verschachtelten x-for-Schleifen, etwa Kategorien mit jeweils eigenen Unterlisten, braucht jede Ebene ihren eigenen, in ihrem jeweiligen Scope eindeutigen :key. Ein Key muss dabei nur innerhalb seiner eigenen Iteration eindeutig sein, nicht global über die gesamte Seite. Zwei verschiedene Kategorien dürfen also durchaus Produkte mit identischer id enthalten, ohne dass es zu Konflikten kommt, solange jede Schleife ihren eigenen :key-Ausdruck korrekt referenziert.

Ein häufiger Fehler bei Verschachtelung ist, den Key der äußeren Schleife versehentlich auch für die innere Schleife zu verwenden, etwa durch Copy-Paste des Templates. Das führt dazu, dass alle inneren Listenelemente denselben Key erhalten und Alpine sie nicht mehr korrekt unterscheiden kann. Jede Ebene braucht ihren eigenen, semantisch passenden Key-Ausdruck, der sich auf die tatsächliche Iterationsvariable dieser Ebene bezieht.

// Verschachtelte x-for: jede Ebene braucht ihren eigenen, korrekten :key
Alpine.data('catalog', () => ({
  categories: [
    { id: 'c1', name: 'Werkzeuge', products: [{ id: 'p1', name: 'Hammer' }, { id: 'p2', name: 'Zange' }] },
    { id: 'c2', name: 'Schrauben', products: [{ id: 'p3', name: 'M4' }, { id: 'p4', name: 'M6' }] }
  ]
}));

// <template x-for="category in categories" :key="category.id">
//   <div>
//     <h3 x-text="category.name"></h3>
//     <ul>
//       <template x-for="product in category.products" :key="product.id">
//         <li x-text="product.name"></li>
//       </template>
//     </ul>
//   </div>
// </template>

// category.id und product.id sind unabhängige, jeweils lokal eindeutige Keys

6. Hinzufügen, Entfernen und Sortieren

Bei dynamischen Operationen wie Hinzufügen, Entfernen oder Sortieren zeigt sich der Wert eines korrekten :key am deutlichsten. Beim Entfernen eines Eintrags aus der Mitte der Liste löscht Alpine mit korrektem :key exakt das zugehörige DOM-Element und verschiebt die verbleibenden Elemente in ihrer bestehenden Identität nach oben, ohne deren internen Zustand zu berühren. Ohne :key würde stattdessen unter Umständen das letzte DOM-Element entfernt und alle davorliegenden Elemente mit falschen Daten überschrieben.

Beim Sortieren, etwa nach Preis oder alphabetisch, ist der Unterschied noch auffälliger: Mit :key ordnet Alpine die bestehenden DOM-Elemente einfach neu an, was für CSS-Transitions auf Positionsänderung wichtig ist. Ohne :key werden stattdessen fast alle Elemente mit neuen Inhalten überschrieben, was jede laufende Transition oder Animation abrupt unterbricht und für den Nutzer wie ein Flackern wirkt statt wie eine sanfte Neuordnung.

// Sortieren mit korrektem :key: DOM-Elemente werden verschoben, nicht neu erzeugt
Alpine.data('sortableList', () => ({
  products: [
    { id: 'a', name: 'Produkt A', price: 29 },
    { id: 'b', name: 'Produkt B', price: 12 },
    { id: 'c', name: 'Produkt C', price: 45 }
  ],
  sortByPrice() {
    this.products.sort((a, b) => a.price - b.price);
  }
}));

// <template x-for="product in products" :key="product.id">
//   <div x-transition class="p-3 border-b" x-text="`${product.name}: ${product.price}€`"></div>
// </template>

// sortByPrice() ändert nur die Array-Reihenfolge -
// mit :key verschiebt Alpine die bestehenden DOM-Elemente sanft

7. Performance-Auswirkungen bei großen Listen

Bei großen Listen mit hunderten oder tausenden Einträgen hat der korrekte :key auch spürbare Performance-Vorteile. Ohne :key muss Alpine im ungünstigsten Fall bei jeder Änderung fast jedes DOM-Element im Listenbereich aktualisieren, weil es keine Möglichkeit hat, unveränderte Datensätze von veränderten zu unterscheiden. Mit einem stabilen :key erkennt Alpine gezielt, welche Elemente sich tatsächlich geändert haben, und aktualisiert nur diese, während unveränderte Elemente unangetastet bleiben.

Dieser Unterschied wird besonders bei Listen mit komplexen Kindelementen relevant, etwa Produktkarten mit Bildern, mehreren verschachtelten Komponenten und Event-Listenern. Jedes unnötig neu erzeugte DOM-Element bedeutet zusätzliche Layout-Berechnung, erneutes Laden von Bildern und erneutes Registrieren von Event-Listenern. Der :key-Modifier minimiert diese Arbeit auf das tatsächlich Notwendige und ist damit auch aus reiner Performance-Sicht kein optionales Detail, sondern eine sinnvolle Grundregel für jede dynamische Liste.

8. Debugging: fehlende oder doppelte keys

Wenn eine Liste sich merkwürdig verhält, Eingaben verschwinden oder Animationen ruckeln, ist die erste Debugging-Frage: Hat das template x-for überhaupt einen :key-Modifier, und liefert der Key-Ausdruck tatsächlich für jeden Eintrag einen unterschiedlichen Wert? Ein häufiger, subtiler Fehler ist ein Key, der zwar vorhanden, aber nicht wirklich eindeutig ist, etwa :key="item.category", wenn mehrere Einträge dieselbe Kategorie teilen. Alpine erkennt doppelte Keys nicht immer mit einer expliziten Warnung, das Symptom zeigt sich stattdessen als unerklärliches Vertauschen von Inhalten zwischen Einträgen mit demselben Key-Wert.

Eine zweite Debugging-Technik: Man setzt testweise ein sichtbares, eindeutiges Attribut wie :data-key="item.id" zusätzlich zum eigentlichen :key und beobachtet in den Entwicklertools, ob dieses Attribut nach einer Listenänderung am erwarteten DOM-Element haften bleibt. Bleibt es an der falschen Position, liegt entweder ein fehlender :key oder eine nicht eindeutige Werte-Quelle zugrunde.

9. Mit key vs. ohne key im Vergleich

Die folgende Übersicht zeigt die konkreten Unterschiede im Verhalten von x-for mit und ohne :key bei typischen Listen-Operationen.

Die Tabelle macht deutlich: :key ist bei x-for keine Mikro-Optimierung, sondern eine Korrektheitsgarantie. Sobald eine Liste mehr als reines Anhängen am Ende erlaubt, sollte :key immer gesetzt sein.

10. Zusammenfassung

Der :key-Modifier bei x-for ist keine kosmetische Ergänzung, sondern die Grundlage für korrekte Listen-Updates in Alpine.js. Ohne stabilen, eindeutigen Key verfolgt Alpine nur die Position eines Elements, nicht seine tatsächliche Datenidentität, was beim Einfügen, Entfernen oder Sortieren in der Mitte einer Liste zu vertauschtem Zustand, Fokus-Bugs und unterbrochenen Animationen führt. Mit einer stabilen ID als Key ordnet Alpine DOM-Elemente ihren Datensätzen korrekt zu, unabhängig von deren aktueller Position.

Der häufigste Fehler ist die Verwendung des Array-Index als Key, weil sich dieser bei jeder Umsortierung ändert und damit genau das Problem reproduziert, das gelöst werden soll. Bei verschachtelten Listen braucht jede Ebene ihren eigenen, lokal eindeutigen Key. Auch aus Performance-Sicht lohnt sich ein korrekter Key bei großen Listen, weil Alpine nur tatsächlich geänderte Elemente aktualisiert, statt fast den gesamten Listenbereich neu zu rendern.

11. FAQ: x-for mit key in Alpine.js