Keys: How React Tells Items Apart

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Key

A special prop (key) that labels an item in a list so React can recognise it on the next render.

Siblings

Elements that share the same parent, like the <li>s in one <ul>.

Unique among siblings

No two items in the same list have the same key. Other lists may reuse it.

Stable key

A key that stays the same for the same item on every render.

Index

An item's position in an array: 0 for the first, 1 for the second, and so on.

Reconciliation

React comparing the new elements with the old ones to decide what to keep, move, add and remove.

Identity

Which item an element *is* across renders. React decides identity by type, position and key.

Fragment

A wrapper that groups elements without adding a DOM element. <Fragment key=...> is the form that takes a key.

crypto.randomUUID()

A browser function that makes a random unique id string, useful when you create a new item.

1. 1

   Do the bug by hand

   In "The bug", press the reset arrow, delete the demo script at the bottom, and run it. Type a note next to Ravi in both lists, then click Add Meera to the top. Predict where each note ends up before you click.

2. 2

   Try Math.random() as a key

   In the stars example, change the right-hand list to key={Math.random()} and delete the demo script. Click a star a few times, then click Reverse order. Predict first: every star count goes back to 0, because every row got a new key and React built new rows with fresh state.

3. 3

   Fix the warning two ways

   In "The missing-key warning", first add key={p.id}. Then remove it and instead try putting key={product.id} on the <li> inside ProductRow. Does the warning come back? (Yes: the key must be on the element in the array, <ProductRow>.)

4. 4

   Try a key on the short Fragment

   In the glossary, replace <Fragment key={t.id}> with <key={t.id}>. The code doesn't even compile: the short <> syntax has no place for attributes.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   Why React needs keys: after each render React compares the new list of children with the old one (reconciliation, Topic 0.2) to decide what to keep, move, add or remove. Each list item may own things that live outside your data: its state (from useState), its DOM nodes (with typed text, focus, scroll position, a playing video). React must know which new item is "the same" as which old one so it can keep those things with it. Without keys it can only match by position: first with first, second with second.

2. 2

   The key rules. A key is the special key prop on the element returned from map: <li key={todo.id}>. (1) Unique among siblings: no two items in the *same* list may share a key. Keys don't need to be unique across the whole app; two different lists may both have an item with key 1. (2) Stable: the same item must get the same key on every render. A key that changes makes React think the old item left and a brand new one arrived. Keys are compared as strings, so 1 and "1" count as the same key.

3. 3

   Where keys come from. Best: an id that is already in the data, such as a database id (user.id, "order-1042"). If you create items in the browser, give each one an id when you create it, in the event handler, not during render: a counter (nextId++) or crypto.randomUUID(). If the items are unique strings themselves (a fixed list of tags), the string can be the key. The key is not passed to your component: props.key is undefined and React warns if you read it. If the child needs the id, pass it again as a normal prop: <Row key={p.id} id={p.id} />.

4. 4

   Why not the index? items.map((item, i) => <Row key={i} />) gives each row the key "my position". That is exactly what React does with no key at all, so it hides the warning without fixing anything. It is fine for a list that never changes order, never gets items inserted or removed except at the end, and whose rows hold no state. But insert an item at the top, delete one, sort or filter, and every key now points at a different item. React keeps each row's state and DOM with the position, so typed text, ticked boxes and counters stay put while the data under them moves: state sticks to the wrong row. You'll watch it happen below.

5. 5

   **Why not Math.random()?** key={Math.random()} gives every item a new key on every render. Nothing ever matches, so React throws away every row and builds it again each time: all row state resets, inputs lose focus and typed text while you type, and the list is slower. Keys must be created once and stored with the data, never computed fresh in render.

6. 6

   The missing-key warning. When you render an array of elements without keys, React's development build prints Each child in a list should have a unique "key" prop. and names the component whose render made the list (Check the render method of ...). Duplicate keys print Encountered two children with the same key. Both are removed in production builds, so fix them while developing. Keys on Fragments: when one item renders several elements with no wrapper (a <dt> and a <dd> in a definition list), you need a Fragment, and the short <> syntax cannot take attributes. Import Fragment and write <Fragment key={t.id}>...</Fragment>.

• ↔

  Index keys are acceptable for truly static lists and save you from inventing ids; the moment a list can change order or hold state, the cost is a silent correctness bug, so default to ids.

• ↔

  Changing a key on purpose is a cheap way to reset a component, but it throws away its DOM and state completely, which can be more work than updating it.

• I can explain why React needs keys to match list items between renders.

• I give every list item a unique, stable key from its data.

• I can show and explain the index-key bug where state sticks to the wrong row.

• I know why Math.random() keys reset every row.

• I can read the missing-key and duplicate-key warnings and fix them.

• I can put a key on a Fragment when an item has several elements.