What this usually means
React uses the key prop to efficiently track items across renders. When you omit keys, or use unstable values (like indexes), React can't correctly match DOM elements to data items. The warning is more than cosmetic: broken or duplicate keys often cause bugs like inputs losing state, elements flickering, or the UI not reflecting the source data accurately after changes.
The first ten minutes — establish facts before touching code.
- 1Reproduce the warning: load the UI in Chrome, open DevTools Console, and trigger any list updates.
- 2Read the stack trace: React's console warning often includes the component stack for the offending list.
- 3Identify list renders: Search source code for `.map(` or `Array.from` usages that return JSX.
- 4Check key assignments: Are you passing a `key` prop to every direct child in arrays?
- 5Verify key uniqueness: Ensure keys are derived from a unique, stable data attribute (not array index).
The specific files, logs, configs, and dashboards that usually own this bug.
- searchComponent files rendering lists (e.g., `UserList.jsx`, `Todos.tsx`)
- searchThe console output in browser DevTools (look for repeated or missing key warnings)
- searchThe data source: verify each item has a unique ID (e.g., `user.id`, `todo.uuid`)
- searchGit history for recent changes to list rendering logic
- searchAny custom list components or wrappers around `.map()`
Practical causes, not theory. These are the things you will actually find.
- warningUsing array index as the key (e.g., `key={i}`)
- warningOmitting the key prop entirely in a list render
- warningUsing a non-unique property as key (e.g., `name` that's not unique)
- warningMapping over a temporary or inconsistent dataset with unstable IDs
- warningKeys mutating or being reassigned between renders
Concrete fix directions. Pick the one that matches your root cause.
- buildAlways use a stable, unique field from item data as the key (e.g., `key={user.id}`)
- buildIf data lacks a unique ID, generate one before rendering (e.g., `uuid` or monotonic counter in state)
- buildAvoid using array indexes as keys except for truly static lists
- buildRefactor custom list components to forward keys properly to their children
- buildWrite tests that simulate adding/removing/reordering items and assert absence of key warnings
A fix you cannot prove is a guess. Close the loop.
- verifiedReload and interact with the UI: confirm no 'key' warnings appear in the console
- verifiedAdd and remove items: check for proper persistence of input/data state
- verifiedDeliberately rearrange list order and verify UI reflects data changes accurately
- verifiedRun `npm run test` or equivalent: add cases that would surface key-related UI corruption
- verifiedAsk a teammate to review for stable key selection (especially after mapping refactors)
Things that make this bug worse or harder to find.
- warningSuppressing the warning in console instead of fixing the root cause
- warningAssuming the warning is harmless if the UI 'looks fine' in basic cases
- warningUsing object references as keys (e.g., `key={item}`) which will break on deep equality
- warningForgetting to update keys when changing the underlying data structure
- warningRelying on indexes for dynamic or re-orderable lists
React Todo List Swaps Inputs Between Items
Timeline
- 09:00Deployed new Todo list feature to staging.
- 09:05QA reports: editing a Todo sometimes updates the wrong item.
- 09:07Console shows: 'Each child in a list should have a unique "key" prop.'
- 09:10Spot check: `key={i}` is used for `.map()` in `TodoList.tsx`.
- 09:14Added/deleted items: observed input state jumping between Todos.
- 09:20Patched code to use `key={todo.id}` instead.
- 09:22Retested: No warning, input states now persist correctly.
- 09:30Pushed hotfix and merged to main branch.
Our team shipped a simple Todo list, confident after passing the smoke tests. Minutes after deploying, QA pinged that editing one task sometimes changed the wrong task below it.
I jumped to the browser console—sure enough, React's key prop warning was blinking. In the code, we'd mapped over the todos array with `key={i}` (the index). I quickly realized that, when reordering or deleting, React couldn't keep track of which input mapped to which Todo.
Replacing the key with the unique `todo.id` fixed both the warning and the phantom input jumps. We learned to treat the key prop warning as a bug—never just console noise.
Root cause
Using array index as key caused React to misalign DOM nodes to data after reorder/delete.
The fix
Switched all list render keys to use `todo.id`, ensuring stable identity.
The lesson
Always use stable, unique keys for dynamic React lists—ignore the warning at your peril.
React's reconciliation algorithm uses the key prop to match existing DOM elements to new data on every render. Without stable keys, React falls back to positional matching, resulting in stateful components (like input fields) unexpectedly swapping, resetting, or duplicating.
Even if duplicate UI doesn't surface immediately, bugs can lurk until you add, remove, or reorder items. This is why React's warning must be taken seriously, even on static-looking lists.
Stable keys are values tied to the conceptual identity of a data item (e.g., a user ID or a permanent UUID). Unstable keys—like array indexes or timestamps—change as items move or are inserted, breaking React's mapping logic.
Inconsistent keys can cause loss of local state (checkboxes appearing unchecked), broken CSS animations, or confusing focus/blur behavior. Always audit the source of your keys, especially after data refactors.
The only safe use of index as key is for a list that's strictly static: no items are added, removed, or reordered after initial render. Even then, prefer a unique field if available.
Dynamic data (e.g., filtering, sorting) makes index keys dangerous. If you must use an index, comment clearly and add tests to guard against future devs breaking this assumption.
Frequently asked questions
Does the key prop get passed as a prop to my component?
No. React uses `key` only for its internal reconciliation. It's never available as a prop inside your component (check: try logging `props.key`—it’s undefined).
Can I use UUIDs for keys if my data doesn't have stable IDs?
Yes—generate UUIDs server-side or at data creation. Never generate new UUIDs on every render, or the keys will be unstable and cause React to remount elements.
Why does my list render fine even with the warning?
It may look fine for now, but the next time data changes (add/remove/reorder), you'll likely see state glitches. The warning means React can't guarantee correct behavior.
What's wrong with using object references as keys?
Object references change on data cloning or serialization. Keys must be stable primitives, not object references; otherwise React can't persist identity after data mutation.