React Listen und Keys: map(), key-Prop, Index als Key

Um in React eine Liste zu rendern, rufst du map() auf einem Array auf und gibst für jeden Eintrag ein Stück JSX zurück. Gib dem äußersten Element jedes Eintrags eine key-Prop mit einem Wert, der diesen Eintrag identifiziert, meist seine ID, damit React die Einträge unterscheiden kann, wenn sich die Liste ändert.

const fruits = [
    { id: 'apl', name: 'Apple', price: 0.5 },
    { id: 'ban', name: 'Banana', price: 0.25 },
    { id: 'chr', name: 'Cherry', price: 3 },
];

export default function App() {
    return (
        <ul>
            {fruits.map((fruit) => (
                <li key={fruit.id}>
                    {fruit.name}: ${fruit.price.toFixed(2)}
                </li>
            ))}
        </ul>
    );
}

Füge { id: 'dat', name: 'Date', price: 4 } zum Array hinzu, und eine vierte Zeile erscheint. JSX hat keine eigene Schleifensyntax: map gibt ein Array von Elementen zurück, und React rendert ein Array, indem es jedes Element der Reihe nach rendert.

Arrays mit map rendern

map ruft deine Funktion einmal pro Eintrag auf und sammelt die Ergebnisse in einem neuen Array. In den geschweiften Klammern von JSX ist dieses Array einfach ein Wert, also kannst du direkt im Markup mappen, wie oben, oder das Array vorher bauen:

const items = fruits.map((fruit) => <li key={fruit.id}>{fruit.name}</li>);
return <ul>{items}</ul>;

Zwei Details bringen Leute ins Stolpern. Wenn du in der Arrow Function geschweifte Klammern nutzt, brauchst du ein return: fruits.map((f) => { return <li key={f.id}>{f.name}</li>; }). Ohne gibt die Funktion undefined zurück, und die Liste ist leer. Und der key gehört an das Element, das aus map zurückkommt, nicht an ein Element darin. Wenn der Eintrag eine Komponente ist, setze den Key auf die Komponente: <FruitRow key={fruit.id} fruit={fruit} />.

Erst filtern, dann mappen

Um einige der Einträge zu zeigen, filtere das Array zuerst und mappe dann das Ergebnis. Jede Methode erledigt eine Aufgabe, und die Kette liest sich wie der Satz „die passenden Früchte, als Listeneinträge“.

import { useState } from 'react';

const products = [
    { id: 1, name: 'Notebook', inStock: true },
    { id: 2, name: 'Pencil', inStock: false },
    { id: 3, name: 'Eraser', inStock: true },
    { id: 4, name: 'Ruler', inStock: false },
    { id: 5, name: 'Stapler', inStock: true },
];

export default function App() {
    const [query, setQuery] = useState('');
    const [onlyInStock, setOnlyInStock] = useState(false);

    const visible = products
        .filter((p) => p.name.toLowerCase().includes(query.toLowerCase()))
        .filter((p) => !onlyInStock || p.inStock);

    return (
        <div>
            <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Search" />
            <label style={{ marginInlineStart: 8 }}>
                <input
                    type="checkbox"
                    checked={onlyInStock}
                    onChange={(e) => setOnlyInStock(e.target.checked)}
                />
                In stock only
            </label>
            {visible.length === 0 && <p>No products match.</p>}
            <ul>
                {visible.map((p) => (
                    <li key={p.id}>{p.name}</li>
                ))}
            </ul>
        </div>
    );
}

Tippe er ins Suchfeld, und die Liste schrumpft auf Eraser, Ruler und Stapler; hake In stock only an, und Ruler verschwindet auch. Die gefilterte Liste wird beim Rendern aus den zwei State-Werten berechnet, also gibt es kein zweites Array im State, das synchron gehalten werden muss. visible.length === 0 && ist eine sichere Verwendung von &&, weil der Vergleich ein echter Boolean ist (die Seite zum bedingten Rendern zeigt, was mit einer nackten 0 passiert).

Was Keys tun

Wenn eine Liste erneut rendert, vergleicht React das neue Array von Elementen mit dem vorherigen. Keys sind die Art, wie es sie zuordnet: Das Element mit Key 3 jetzt ist das Element mit Key 3 von vorher, auch wenn es sich bewegt hat. React behält den DOM-Knoten und den Komponenten-State dieses Eintrags und verschiebt oder aktualisiert nur, was sich geändert hat. Einträge mit neuen Keys werden erzeugt, und verschwundene Keys werden entfernt.

Ohne Keys kann React nur nach Position zuordnen. Das passt, solange sich nichts bewegt, und ist falsch, sobald sich etwas bewegt.

Warum Index-Keys brechen

map übergibt den Index als zweites Argument, also ist key={index} verlockend. Der Index beschreibt eine Position, keinen Eintrag. Füge oben einen Eintrag ein, und der Index jedes Eintrags verschiebt sich um eins, also glaubt React, Eintrag 0 sei immer noch Eintrag 0, und behält dort seinen alten State.

Die Demo unten rendert dieselbe Liste zweimal, einmal mit Index als Key und einmal mit ID. Jede Zeile hat ein Eingabefeld, das seinen eigenen Text behält.

import { useState } from 'react';

let nextId = 3;

export default function App() {
    const [people, setPeople] = useState([
        { id: 1, name: 'Ada' },
        { id: 2, name: 'Linus' },
    ]);

    function addToTop() {
        setPeople([{ id: nextId, name: 'New person ' + nextId }, ...people]);
        nextId++;
    }

    return (
        <div style={{ display: 'flex', gap: 24, flexWrap: 'wrap' }}>
            <div>
                <b>key=&#123;index&#125;</b>
                {people.map((p, index) => (
                    <p key={index}>
                        {p.name}: <input placeholder="note" size={10} />
                    </p>
                ))}
            </div>
            <div>
                <b>key=&#123;p.id&#125;</b>
                {people.map((p) => (
                    <p key={p.id}>
                        {p.name}: <input placeholder="note" size={10} />
                    </p>
                ))}
            </div>
            <button onClick={addToTop} style={{ alignSelf: 'start' }}>Add to top</button>
        </div>
    );
}

Tippe in beiden Listen math neben Ada und klicke dann auf Add to top. In der ID-Liste bleibt die Notiz bei Ada. In der Index-Liste springt die Notiz zur neuen Person, weil das erste Eingabefeld immer noch das Eingabefeld an Position 0 ist, und Position 0 ist jetzt jemand anderes. Die Namen stimmen in beiden Listen, weil sie aus den Daten kommen; nur der State, der im DOM und in Komponenten lebt, geht schief. Echte Apps stoßen darauf bei Checkboxen, Fokus, Animationen und jeder Komponente, die useState hält.

Index-Keys sind nur sicher, wenn alles davon zutrifft: Die Liste wird nie umsortiert oder gefiltert, Einträge werden nie eingefügt oder entfernt außer am Ende, und die Einträge haben keinen eigenen State. Eine statische Liste von Footer-Links erfüllt das. Alles, was jemand bearbeiten kann, meist nicht.

Woher Keys kommen

Der beste Key ist eine ID, die schon in den Daten steckt: eine Datenbank-ID, eine Artikelnummer, ein Slug, ein Benutzername. Daten von einem Server haben fast immer eine.

Für Einträge, die im Browser entstehen, gib jedem Eintrag beim Anlegen eine ID und speichere sie mit dem Eintrag: einen Zähler, wie in der Demo oben, oder crypto.randomUUID(). Erzeuge den Key niemals beim Rendern:

// Wrong: a new key on every render, so React remounts every item every time
{todos.map((todo) => <Todo key={Math.random()} todo={todo} />)}

// Right: the ID is created once, in the event that adds the item
function addTodo(text) {
    setTodos([...todos, { id: crypto.randomUUID(), text }]);
}

Ein Key, der sich bei jedem Render ändert, ist schlimmer als ein Index: Jeder Eintrag wird jedes Mal zerstört und neu erzeugt, Eingabefelder verlieren beim Tippen den Fokus, und nichts behält seinen State. Derselbe Trick ist absichtlich nützlich: Den Key einer Komponente zu ändern setzt sie zurück, und die Seite zu useState nutzt das, um ein Formular zu leeren.

Keys sind nur unter Geschwistern eindeutig

Ein Key muss innerhalb einer Liste eindeutig sein, nicht in der ganzen App. Zwei getrennte Listen können dieselben IDs wiederverwenden, weil React Keys nur unter den Kindern desselben Elternelements vergleicht.

const menu = [
    { id: 1, section: 'Breakfast', dishes: [{ id: 1, name: 'Pancakes' }, { id: 2, name: 'Omelette' }] },
    { id: 2, section: 'Lunch', dishes: [{ id: 1, name: 'Soup' }, { id: 2, name: 'Salad' }] },
];

export default function App() {
    return (
        <div>
            {menu.map((part) => (
                <section key={part.id}>
                    <h4 style={{ marginBottom: 4 }}>{part.section}</h4>
                    <ul style={{ marginTop: 0 }}>
                        {part.dishes.map((dish) => (
                            <li key={dish.id}>{dish.name}</li>
                        ))}
                    </ul>
                </section>
            ))}
        </div>
    );
}

Beide Abschnitte haben Gerichte mit den Keys 1 und 2, und das ist korrekt: Jedes ul ist eine eigene Liste. Doppelte Keys innerhalb einer Liste sind das Problem: React kann die kollidierenden Einträge nicht unterscheiden und kann sie beim Update der Liste doppeln oder verlieren.

Wenn ein Eintrag mehrere Geschwisterelemente rendert, etwa ein <dt> und ein <dd>, umschließe sie mit <Fragment key={item.id}>. Die kurze Syntax <> kann keinen Key annehmen.

Die Warnung „unique key prop“

Wenn du den Key weglässt, gibt React in der Entwicklung dies in der Browserkonsole aus:

Each child in a list should have a unique "key" prop.

Check the render method of `App`.

Die zweite Zeile nennt die Komponente, deren Render die Liste erzeugt hat, und sagt dir so, welches map du korrigieren musst. Zwei Geschwister mit demselben Key bekommen eine andere Meldung, die mit „Encountered two children with the same key“ beginnt. Die Vorschau auf dieser Seite läuft wie ein Produktions-Build, der diese Prüfung überspringt, also siehst du die Warnung hier nicht, selbst wenn du einen key löschst. Lösch trotzdem einen im ersten Beispiel: Die Liste rendert weiter, weil ein fehlender Key ein Risiko für die Korrektheit ist, kein Absturz. Um die Warnung zu beheben, setze einen stabilen Key auf das aus map zurückgegebene Element; key={index} bringt sie zum Schweigen, holt aber den oben gezeigten Bug zurück.

Beachte außerdem, dass key nicht an deine Komponente übergeben wird. In FruitRow ist props.key gleich undefined. Wenn die Komponente die ID braucht, übergib sie ein zweites Mal als normale Prop: <FruitRow key={f.id} id={f.id} />.