Keys and List Reconciliation

## The problem the reconciler is solving Rendering a list gives React two flat sequences of elements: the children this parent produced last render, and the children it just produced. It has to answer one question per new element — "which of the old ones are you?" — because the answer decides whether an existing fiber (with its hook state, its refs, its real DOM node) is updated in place, or thrown away and rebuilt. A true minimal-edit-distance tree diff is too expensive to run on every keystroke, so React uses a linear pass with one hint from you: the key. ## Without keys: pairing by position If the children carry no key, React treats position as identity. New child at index *i* is paired with the previous child at index *i*. If they are the same element type, the fiber is reused and its props are updated; if the type differs, that fiber is deleted and a new one is created for the slot. Extra new children at the end are mounted; leftover previous children at the end are deleted. This is exactly what array-index keys do, which is why index keys and no keys behave identically apart from the development warning. ## With keys: pairing by name With keys, the pass has two stages. **Stage one — walk in parallel.** React steps through both lists together. As long as the new child's key equals the old child's key at the same position, it pairs them immediately. For a list that did not change, or that only had items appended or had props updated in place, the whole reconciliation is this cheap linear walk and nothing else runs. **Stage two — the map.** At the first position where the keys disagree, the parallel walk stops, because from here on positions no longer correspond. React puts every remaining previous child into a map keyed by its key (children without a key are stored under their index). Then it continues through the remaining new elements, looking each one up in that map: - **Hit** — the previous fiber is pulled out of the map and reused. React also tracks how far along the previous list it has already placed things; if this fiber came from an earlier position than that watermark, it is flagged so the commit phase moves its DOM node with an insertion, rather than recreating it. - **Miss** — no previous child owned that key, so a new fiber is created and mounted. Whatever is still in the map when the new list is exhausted was not claimed by anyone, so those fibers are deleted: their effect cleanups run, their refs are detached, their DOM nodes are removed. ## Key is checked before type This ordering surprises people. React first asks "do the keys match?" and only then "is it the same element type?". Two consequences: - Same key, different type (`<Row key="a" />` becomes `<Card key="a" />`): the fiber is not reused. The old one is deleted, a new one is mounted. - Different key, same type: also no reuse. The key mismatch alone is enough to discard the fiber, even though the component is identical. ## What "reuse" actually means Reusing a fiber is not a shallow optimisation — it is what makes a component feel continuous: - the fiber's hook state list survives, so `useState` values, `useRef` boxes and reducer state are exactly what they were; - the host DOM node survives, so uncontrolled input values, focus, text selection, scroll position and running CSS transitions survive; - effects are not torn down; they re-run only if their dependencies changed. Moving a reused fiber is cheap too: the commit phase performs an insertion of the existing node at the new position. Nothing is re-created. ## Why the hint has to come from you React cannot infer identity from the data — it never sees your objects, only elements. The key is the one place you tell it "this element is the same thing as the one that had this name last time". Everything else in list reconciliation follows mechanically from that one input, which is why a key derived from something unstable poisons the whole process. ## Answering well Name the two stages (parallel walk, then map lookup), say that the key is compared before the type, and finish with what reuse buys — fiber state and DOM node preserved, versus delete-and-mount when nothing matches.