What properties must a list key have to be usable, and which common key sources fail them?

## What the pairing step needs from you When a runtime updates a list, it pairs the children it built last time with the children described now, and a key is the identity it uses to do that. Four properties make a value fit for the job. 1. **It comes from the data.** A key answers *which item is this*, so it has to be a property of the item — a record id — not a property of the render, such as where the item happens to sit this time. 2. **It is stable.** The same item carries the same key on every update, through reorders, filters, pagination and refetches. If a key changes, the runtime is being told the item was replaced. 3. **It is unique among its siblings.** The comparison only ever happens inside one parent's children, so uniqueness is required there and nowhere else. 4. **It is cheap and simple to compare.** Runtimes generally use a plain equality check, so a string or a number behaves predictably. ## The common sources, and how they score | Key source | Verdict | What goes wrong | |---|---|---| | A stable id carried by the record | Correct | nothing — this is the intended source | | A composite of fields that jointly identify the item | Correct if truly unique and stable | breaks the moment one of those fields becomes editable | | The item's index in the list | Fails *from the data* | it is positional matching under another name, and it silences a missing-key warning | | A value generated while rendering | Fails *stable* | every key is new every update, so nothing pairs | | A field that can repeat, such as a category label | Fails *unique among siblings* | ambiguous pairing: a row silently missing, or two rows sharing one instance | | An editable field, such as a display name | Fails *stable* | editing the field changes the key, discarding the row's instance mid-edit | | A freshly built object or array | Fails *cheap to compare* | it compares unequal each update, behaving like a generated key | ## Why a generated key is worse than an index An index at least pairs something: rows keep their instances, and the bug is that the *wrong* rows keep them. A key minted during the update pairs nothing. Every new key is unknown, so every child is created, and every old key has vanished, so every instance is destroyed. On every single update the list is rebuilt from nothing: - all per-row state resets, including scroll positions and expanded sections; - focus and any in-progress text entry are lost, so a user cannot finish typing; - host nodes are recreated rather than moved, so entry animations replay on rows that never moved; - teardown and setup work runs for every row, which may mean re-subscribing or re-requesting; - the runtime's own skip-work strategies cannot help, because nothing is recognised as unchanged. It looks like a fix — the warning goes away and every value is unique — and it is the most expensive mistake in this area. ## Sibling scope, stated precisely Keys are compared inside one sibling list. That means two separate lists on the same screen may each use `1, 2, 3` with no interaction, a nested list has its own scope independent of its parent's, and the same key value appearing in a different part of the tree is not a conflict. It also means a rule mandating globally unique keys is over-constraint: it teaches the wrong requirement and pushes teams into synthesising keys where a plain id would do. ## When the data has no identity This is where index keys actually come from — not laziness, but a payload with nothing to key by. The options, in order of preference: 1. **Get one into the data.** Ask the producer for an id. Identity is a property of the entity, so this is the correct place to solve it once for every consumer. 2. **Compose one.** Combine fields that together identify the item and are not user-editable. Verify uniqueness in development rather than assuming it. 3. **Mint one at creation.** For rows that exist only on the client — an empty row a user just added — generate an identifier **when the row is created** and store it alongside the row's data. That is stable, because it is created once, not once per update. Generating it during the render is the failure above. 4. **Accept the index** only for a list that is stateless and never changes shape except at the end, and write down why. ## The one-line test Ask: *if this list were shuffled, would each key still point at the same item?* An id passes. An index does not. A name the user can edit passes the shuffle but fails the edit — which is why the property to check is stability over the whole life of the item, not just over one reorder.