ReactError Fix2026 Updated

React Key Prop Warning— Each Child Must Have Unique Key [2026]

Understand why keys matter, stable IDs vs index, and Fragment keys

January 20265 min readReact 18 · Next.js

⚡ Quick Fix

component.jsx
// ❌ WRONG — no key
{items.map(item => <li>{item.name}</li>)}

// ✅ CORRECT — stable unique ID as key
{items.map(item => <li key={item.id}>{item.name}</li>)}

Why React Needs Keys

React uses keys to match elements between renders. Without them, React cannot tell which list item was updated, added, or removed — so it re-renders the entire list. Keys enable React's reconciliation algorithm to make targeted, efficient updates.

1

Add key to Every Mapped Element

The warning — key missing from outermost element
1 min
components/UserList.jsx
// ❌ WRONG — no key
{users.map(user => (
  <div className="card">
    <p>{user.name}</p>
  </div>
))}

// ✅ CORRECT — key on outermost element returned by map
{users.map(user => (
  <div key={user.id} className="card">
    <p>{user.name}</p>
  </div>
))}
2

Use Stable Unique IDs as Keys

Best key — from your database or API
2 min
component.jsx
// ✅ Database ID — best key
{posts.map(post => <Post key={post.id} post={post} />)}

// ✅ Slug — stable, readable
{pages.map(page => <Page key={page.slug} page={page} />)}

// ✅ Compound key — when single field is not unique
{items.map(item => (
  <Item key={`${item.category}-${item.id}`} item={item} />
))}
3

When Index as Key Is Acceptable

Static lists that never change order
2 min
component.jsx
// ✅ OK to use index — static list, no reorder/add/remove
const STEPS = ['Choose plan', 'Enter details', 'Confirm']
{STEPS.map((step, i) => <Step key={i} label={step} />)}

// ❌ BAD — dynamic list with add/remove/sort
{todos.map((todo, i) => (
  <TodoItem key={i} todo={todo} />  // state will shift when item removed!
))}

// ✅ CORRECT for dynamic list — use stable ID
{todos.map(todo => (
  <TodoItem key={todo.id} todo={todo} />
))}

Using index as key on a dynamic list causes bugs with controlled inputs and component state. When item 2 is deleted, item 3 becomes index 2 and inherits item 2's state.

4

Keys on Fragments

key prop on React.Fragment
1 min
component.jsx
import { Fragment } from 'react'

// ❌ WRONG — short syntax <> doesn't support key
{items.map(item => (
  <>
    <dt>{item.term}</dt>
    <dd>{item.definition}</dd>
  </>
))}

// ✅ CORRECT — use Fragment with key
{items.map(item => (
  <Fragment key={item.id}>
    <dt>{item.term}</dt>
    <dd>{item.definition}</dd>
  </Fragment>
))}
5

Keys Must Be Unique Among Siblings Only

Scope of key uniqueness
1 min
component.jsx
// ✅ Same key in different lists is fine
<ul>
  {categoryA.map(item => <li key={item.id}>{item.name}</li>)}
</ul>
<ul>
  {categoryB.map(item => <li key={item.id}>{item.name}</li>)} // same IDs OK
</ul>

// ❌ Duplicate keys in SAME list — React warns
{allItems.map(item => <Item key={item.categoryId} item={item} />)}
// if multiple items share categoryId → duplicate key warning

Prevention

Frequently Asked Questions

Why does React need a key prop on list items?+
React uses keys to identify which items in a list have changed, been added, or removed. Without keys, React re-renders the entire list on every change. With stable, unique keys, React can update only the items that changed — much more efficient.
Can I use array index as a key in React?+
Only if the list is static and never reordered or filtered. Using index as key when items can be added, removed, or reordered causes bugs: state tied to an item moves to the wrong item. Use a stable unique ID from your data whenever possible.
React key warning but I already added a key — why?+
Common causes: 1) The key is on the wrong element — it must be on the outermost element returned by map, 2) The key is not unique among siblings, 3) Using an undefined value as key (console.log the key to verify it is defined and unique).
How do I generate a key for items without IDs?+
If items have no natural ID: use a combination of fields that together are unique: key={item.name + '-' + item.date}. Or use crypto.randomUUID() when creating items. Avoid using Math.random() as key — it changes on every render causing unnecessary remounts.
Do keys need to be globally unique across the whole app?+
No. Keys only need to be unique among siblings — elements at the same level in the same list. The same key can appear in different lists without conflict.
Does adding key fix performance or just silence the warning?+
Both. The warning tells you React cannot efficiently update your list. Adding proper unique keys enables React's reconciliation algorithm to make targeted DOM updates instead of re-rendering the entire list. This is a real performance improvement, not just silencing a warning.

Need Expert Help?

We Build Production-Grade React Apps

Softplix builds full-stack React and Next.js applications. Need help with list rendering or performance optimisation? We can help.

Talk to an Engineer