Each Child in a List Should Have a
Unique "key" Prop — Complete Guide
React 19 • Next.js 15 • TypeScript • Vite • React Router • Redux Toolkit
🔑 What Is the “Unique Key Prop” Warning?
The “Each child in a list should have a unique 'key' prop”
warning is one of the most common React warnings. It appears when you render
a list of elements without providing a key prop, or when the
key values are not unique.
The full warning message reads:
Warning: Each child in a list should have a unique "key" prop.
Check the render method of `YourComponent`. See https://reactjs.org/link/warning-keys for more information.
Why does this matter? The key prop helps React
identify which items have changed, been added, or been removed in a list.
Without proper keys, React may re-render the entire list unnecessarily,
causing performance issues and potential bugs.
⚡ Quick Reference — Key Usage at a Glance
key={item.id} from your data.key={index} only if list is static and won't reorder.key={Math.random()} causes full re-renders every time.📋 The Golden Rules of React Keys
-
Use stable, unique IDs from your data (e.g.,
item.id,item.uuid). - Use index as fallback only when the list is static and items never reorder.
- Never use Math.random() or other unstable values as keys.
- Keys must be stable — they shouldn't change between renders.
- Keys only need to be unique among siblings, not globally unique.
- Keys are not passed as props to child components — they're internal to React.
🧩 Detailed Breakdown — Every Key Scenario Solved
Each card below dives deep into one specific scenario involving React keys, with root causes, code examples, and step-by-step fixes.
🛡️ Prevention — Avoid Key Warnings
Most data from APIs includes unique IDs. Use
key={item.id} in your .map() calls.
When creating new items client-side, use
crypto.randomUUID() or a library like uuid.
If your list never changes (e.g., static navigation items),
key={index} is acceptable.
Add
eslint-plugin-react with the react/jsx-key rule to catch missing keys during development.
If your list can be sorted, filtered, or reordered, use stable IDs instead of index.
❓ Frequently Asked Questions
React uses keys to identify which items in a list have changed, been added, or been removed. This helps React's reconciliation algorithm update the DOM efficiently.
Without keys, React would have to re-render the entire list whenever any item changes, which is slower. With keys, React can update only the items that actually changed.
It depends. Using index as key is safe
when:
- The list is static (never changes).
- The list is never reordered or filtered.
- Items are never added or removed from the list.
However, if the list can change, using index can cause bugs like incorrect component state and unnecessary re-renders.
No. React 19 uses the same key reconciliation algorithm as React 18. The key warning and its behavior remain unchanged.
React 19 introduces new features like the use hook and
useOptimistic, but the core reconciliation algorithm
and key requirements are the same.
Each level of a nested list needs its own unique keys. Keys only need to be unique among siblings, not globally.
// ✅ Correct — keys at each level
function NestedList({ data }) {
return (
<ul>
{data.map(category => (
<li key={category.id}>
<h3>{category.name}</h3>
<ul>
{category.items.map(item => (
<li key={item.id}>{item.name}</li>
))}
</ul>
</li>
))}
</ul>
);
}
The category.id and item.id don't need to be
unique across different levels — only within their own sibling lists.
Yes! Keys work the same way regardless of your state management or routing library.
With Redux Toolkit: Use IDs from your Redux state as keys.
// ✅ With Redux Toolkit
function TodoList() {
const todos = useSelector(state => state.todos);
return (
<ul>
{todos.map(todo => (
<li key={todo.id}>{todo.text}</li>
))}
</ul>
);
}With React Router: Use route IDs or item IDs as keys.
// ✅ With React Router
function PostList({ posts }) {
return (
<div>
{posts.map(post => (
<Link key={post.id} to={`/post/${post.id}`}>
{post.title}
</Link>
))}
</div>
);
}Keys work the same way in Next.js 15 server components as in client components. However, server components render on the server, so the key warning will appear in the server logs.
// ✅ Correct — keys in server component
async function PostList() {
const posts = await fetchPosts();
return (
<div>
{posts.map(post => (
<article key={post.id}>
<h2>{post.title}</h2>
</article>
))}
</div>
);
}key
prop in server components just like in client components. The same rules apply.
0 Comments
thanks for your comments!