React's 'unique key prop' warning: why index keys break your UI

Most developers silence the key warning with key={index} and move on. The warning goes away; the bug stays. Keys are how React matches list items across renders, and an index key tells React 'position 2 is always the same item' - which becomes a lie the moment you insert, delete, sort, or filter.

What goes wrong with index keys - concretely

Render a list of rows, each containing an uncontrolled input. Type into row 1, then delete row 0. React sees the same keys (0, 1, ...) and reuses the DOM: your typed text now sits next to the wrong row's data. The same mechanism scrambles checkbox state, focus, CSS transitions, and component-local state on reorder. It's one of the hardest bugs to reproduce because it only appears after mutation.

// ❌ Breaks on insert/delete/sort
{todos.map((todo, i) => <TodoRow key={i} todo={todo} />)}

// ✅ Stable identity from your data
{todos.map((todo) => <TodoRow key={todo.id} todo={todo} />)}

Choosing a key when there's no id

• A unique field or combination from the data itself - email, slug, `${userId}-${date}`.
• Generate ids when the item is CREATED (crypto.randomUUID() in the add handler), then keep them - never during render.
• Index is acceptable only when the list never reorders, never filters, and items have no state - a static footer nav, say.
• Never key={Math.random()} - a new key every render remounts every item, destroying state and performance in one move.

Keys as a feature: resetting state on purpose

// Changing the key remounts the component - a clean state reset
<ProfileForm key={selectedUserId} userId={selectedUserId} />

The same mechanism that makes wrong keys dangerous makes deliberate keys powerful. Keying a form by the record it edits guarantees fresh state per record - no manual useEffect resets, no leftover validation errors from the previous user.

A key answers one question: 'is this the same item as last render?' If your key can't answer that truthfully after a sort or delete, it's the wrong key.

Written by Appesto Engineering.