Keys and lists

A key is the identity React uses to match a child to its instance between renders — not a cosmetic prop. When a list re-renders, React pairs the new elements with the previous ones by key, within the same parent. Matched keys reuse the existing component instance (and its state, DOM node, effects, focus); unmatched keys mount fresh or unmount. The position in the array is not the identity — the key is.

// React reads keys to answer: "is this the SAME row as last render, or a new one?"
{rows.map((row) => (
  <EditableRow key={row.id} row={row} /> // identity = row.id, stable across reorders
))}

So the rule “keys must be stable and unique among siblings” is not style advice — it’s the contract that lets React keep each row’s state glued to the right data.

Using the array index as the key ties identity to position, so any reorder/insert/delete reassigns state to the wrong row. With key={index}, the first item is always “key 0”. Delete the first row and the second row becomes key 0 — so React thinks the old first instance survived and just got new props. The component instance (with its local state) stays put while the data shifts underneath it.

// BUG: key = position. Local state (input value, focus) is pinned to a slot, not an item.
{items.map((item, index) => (
  <Row key={index} item={item} /> // <input> inside Row holds uncontrolled value
))}

This is invisible for static, append-only lists — which is why index keys pass review for so long. The corruption only fires the first time the list reorders, inserts at the front, or deletes from the middle. That delay is exactly what makes it a senior bug: it ships, then surfaces in production under real user editing.

Fix it with a key that comes from the data and never changes for that item — a database id, a UUID assigned at creation, anything stable. Now identity follows the item, not the slot. Reorder the array and React re-pairs each instance to its data by id, carrying the input value and focus along with it.

// FIX: key = the item's own stable id. Identity now travels with the data.
{items.map((item) => (
  <Row key={item.id} item={item} />
))}

// if your data has no id, assign one ONCE at creation — never during render:
const add = (text: string) =>
  setItems((prev) => [...prev, { id: crypto.randomUUID(), text }]);

The id must be minted when the item is created and stored in the data, not computed in the render body. A key generated inside map is recomputed every render — which is the next failure mode.

Two deliberate uses of keys mark the boundary of correct usage — and one common abuse. Intentionally changing a key is a feature: when you give a subtree a new key, React unmounts the old instance and mounts a fresh one, resetting all its state. That is the idiomatic way to clear a form when the edited entity changes.

// INTENTIONAL remount: switching userId resets every field/scroll/uncontrolled input inside.
<ProfileForm key={userId} userId={userId} />

The abuse is the inverse: a random key on every render. React never matches anything, so it tears down and rebuilds the whole list each render — losing all state and paying full mount cost continuously.

// ANTI-PATTERN: a fresh key every render → total remount each time.
{items.map((item) => (
  <Row key={Math.random()} item={item} /> // never reuses an instance — state + perf gone
))}

Index keys attach state to the wrong row; random keys attach it to no row. Stable ids are the only correct default — and a changing key is correct only when reset-on-change is the intent.