Keys and lists

Rendering a list is a map that returns elements:

<ul>
  {todos.map((todo) => (
    <TodoRow key={todo.id} todo={todo} />
  ))}
</ul>

The previous lesson matched children by position. For a list that can be reordered, filtered or prepended to, position is the wrong identity: the third row today may be a different todo from the third row yesterday. A key replaces position as the identity. Among siblings, React matches the new child with key "42" to the old child with key "42", wherever each of them sits, and that instance keeps its state and DOM node. Keys that disappear are unmounted; new keys are mounted.

Why the index is a bad key

Using the array index as the key (or giving no key, which falls back to the index and logs a warning) is the same as positional matching. It works until the list changes anywhere but the end. Here each row holds some local state — an unsaved draft in an input — and a new item is added to the top:

1// Each mounted row keeps its own local "draft" state, stored by key.2function rerender(prevStates, items, keyOf) {3  const next = {};4  return items.map((item, index) => {5    const key = keyOf(item, index);6    const draft = key in prevStates ? prevStates[key] : "";7    next[key] = draft;8    return `${item.text} [draft: "${draft}"]`;9  });10}11 12export function run() {13  const before = [14    { id: 7, text: "Write report" },15    { id: 3, text: "Buy milk" },16  ];17  const after = [{ id: 9, text: "Call Sam" }, ...before];18 19  // State the user typed while the first list was on screen:20  const byIndex = { 0: "draft for report", 1: "2 litres" };21  const byId = { 7: "draft for report", 3: "2 litres" };22 23  return {24    indexKeys: rerender(byIndex, after, (item, i) => i),25    idKeys: rerender(byId, after, (item) => item.id),26  };27}

With index keys, every row was matched with whatever sat at its index before: the brand-new "Call Sam" row took the draft that belonged to "Write report", "Write report" (now at index 1) took the "2 litres" draft that belonged to "Buy milk", and "Buy milk", at an index that did not exist before, started empty. The data is right and the state is attached to the wrong rows. With id keys every draft stays with its own item, and only the new row starts empty.

What makes a good key

• Stable: the same item gets the same key on every render. An id from your data is ideal. Math.random() or crypto.randomUUID() called during render produces a new key every time, so every row remounts on every render.
• Unique among siblings: keys only need to differ within one list, not across the whole app.
• Not derived from position: the index is fine only for a static list that never reorders, filters or inserts.

The key goes on the element returned from map, not on something inside it. If map returns several elements per item, wrap them in <Fragment key={id}> (the short <> syntax cannot take a key). And a component cannot read its own key — pass the id as a separate prop if it needs it.

A key resets state on purpose

Since a different key means a different instance, changing a key is the cleanest way to reset a component. <ProfileForm key={userId} /> gives each user a fresh form, with no effect copying props into state.

Common mistakes

• Index keys on a list that changes. After an insert, filter or sort, state (input text, checked boxes, open panels) sticks to positions instead of items, as the example models.