How it works
React 19.3.1's reconcileChildrenArray (implementation detail, ReactChildFiber.js) runs in passes:
- Walk old and new children together while keys match at the same index, updating in place.
- If the new list ran out, delete the rest; if the old one ran out, create the rest.
- Otherwise put the remaining old children in a
Map by key (by index when unkeyed) and look up each new child there. Matches are reused; leftovers in the map are deleted.
For reused children, placeChild tracks lastPlacedIndex, the highest old index kept in place so far. A child whose old index is lower is flagged to move; otherwise it stays and raises that mark. The scan only goes forward, so an item moved to the front makes everything after it move. Counting DOM operations with a MutationObserver shows the consequence:
const list = (items, keyOf) => <ul>{items.map((item, i) => <li key={keyOf(item, i)}>{item}</li>)}</ul>;
const byItem = (item) => item;
const byIndex = (_, index) => index;
flushSync(() => root.render(list(['A', 'B', 'C', 'D'], byItem)));
const observer = new MutationObserver(() => {});
observer.observe(container, { subtree: true, childList: true, characterData: true });
function show(items, keyOf) {
const before = new Set(container.querySelectorAll('li'));
flushSync(() => root.render(list(items, keyOf)));
const records = observer.takeRecords();
const added = records.flatMap((r) => [...r.addedNodes]);
const moved = added.filter((node) => before.has(node));
const textEdits = records.filter((r) => r.type === 'characterData').length;
console.log(`moved ${moved.map((n) => n.textContent).join('') || '-'}, created ${added.length - moved.length}, text edits ${textEdits}`);
}
show(['B', 'C', 'D', 'A'], byItem); // → moved A, created 0, text edits 0
show(['A', 'B', 'C', 'D'], byItem); // → moved BCD, created 0, text edits 0
show(['A', 'B', 'C', 'D'], byIndex); // → moved -, created 4, text edits 0
show(['D', 'A', 'B', 'C'], byIndex); // → moved -, created 0, text edits 4
show(['D', 'A', 'B', 'C'], () => Math.random()); // → moved -, created 4, text edits 0
Chrome 156 and Firefox 159, development and production builds; container is the root's DOM node. Moving A to the end cost one move; moving it back to the front cost three, because A's old index was the highest. Switching from item keys to index keys remounted everything, since no key matched. With index keys a reorder became four text edits on the same nodes, which is exactly how state ends up on the wrong item.
Edge cases
key in development. React defines a warning getter, so 'key' in props was true in the development build and false in production; the value is undefined in both. The warning reads Item: `key` is not a prop. Trying to access it will result in `undefined` being returned. followed by advice to pass a different prop.
- Keys on Fragments.
<Fragment key={post.id}><dt>…</dt><dd>…</dd></Fragment> keys a group without adding a DOM wrapper.
- Same key, different type at the same spot still remounts: the key match is checked first, then the type.
- Keys aren't global. A keyed item moved to another parent is unmounted and remounted.
Real-world scenario
A sortable table with an "edit" toggle per row keeps isEditing in each row's state. With key={index}, sorting by name leaves the editor open on whatever row is now third. With key={row.id}, the open editor travels with its row. The same applies to animations and focus: keyed rows keep their DOM nodes, so a focused input stays focused after a sort.
Trade-offs
Keys hand the reconciler the identity information that a cheap O(n) diff can't infer. The cost is on you: the data needs stable ids, and the algorithm, being forward-only, sometimes moves more nodes than necessary (the "move to front" case). For very long lists, those moves matter less than rendering fewer items in the first place, with virtualization.