# How to Provide a Unique React Key for Array Children: Best Practices and Performance Optimization
> Learn best practices for unique React keys in array children. Use stable IDs for O(N) reconciliation, preserve state, and optimize performance. Avoid performance issues.
- Repository: [Meta/react](https://github.com/facebook/react)
- Tags: best-practices
- Published: 2026-02-16
---
**Use a stable, intrinsic identifier (like `item.id`) as the `key` prop when rendering lists in React to enable O(N) reconciliation, preserve component state, and prevent unnecessary DOM operations.**
When rendering dynamic lists in the `facebook/react` repository, providing a **unique React key for array children** is essential for the reconciler to efficiently update the UI. Without stable keys, React cannot distinguish between moved, added, or removed items, leading to degraded performance and potential state bugs. This guide explains the internal mechanics of key validation and the exact best practices derived from the React source code.
## Why a Unique React Key Matters for Array Children
React reconciles UI updates by comparing the current component tree with the previous one. When a component renders an array of children, the **key** prop lets the reconciler quickly match each child to its previous instance using an internal map.
Providing a unique React key for array children enables three critical optimizations:
1. **Identify moved, added, or removed items** without re-creating every element.
2. **Preserve component state** (e.g., `useState` inside a list item) because the same component instance is reused.
3. **Avoid unnecessary DOM operations**, which boosts rendering performance, especially for large lists.
According to the React source code, missing or duplicate keys force the reconciler to fall back to a full diff, increasing work by **O(N²)** in worst-case scenarios. Stable keys restore the expected **O(N)** reconciliation cost.
## How React Validates Keys Internally
In development mode, React validates that each sibling has a unique "key" prop and throws a warning if it does not. The validation lives in the reconciler at:
```text
packages/react-reconciler/src/ReactChildFiber.js
```
The relevant code emits the warning:
```js
console.error(
'Each child in a list should have a unique "key" prop.' +
'%s%s See https://react.dev/link/warning-keys for more information.',
currentComponentErrorInfo,
childOwnerAppendix,
);
```
(source: [ReactChildFiber.js L221-L227](https://github.com/facebook/react/blob/main/packages/react-reconciler/src/ReactChildFiber.js#L221-L227))
This warning appears when React detects children with duplicate or missing keys during the reconciliation process.
## Best Practices for Unique React Keys in Arrays
### Use Stable Intrinsic Identifiers
Always prefer a value that uniquely identifies the data item, such as `item.id` from a database. This ensures the key remains consistent across renders regardless of array position.
```tsx
function TodoList({todos}: {todos: Array<{id: string; text: string}>}) {
return (
{todos.map(todo => (
- {todo.text}
// ✅ stable unique key
))}
);
}
```
### Avoid Using Array Index as a Key
Using `key={index}` is only acceptable when the list never changes order, never inserts or removes items, and the items have no internal state. In all other cases, the index causes state leakage and extra re-renders because React cannot distinguish between items when the array shifts.
```tsx
// ❌ Bad: using index as key when items can reorder
items.map((item, index) => {item.name});
```
### Never Generate Random Keys on Render
Generating keys with `Math.random()` or `Date.now()` on every render defeats the purpose of keys. Because the key changes on every render, React treats each element as new, destroying and recreating DOM nodes unnecessarily.
```tsx
// ❌ Bad: random key on every render
items.map(item => {item.name});
```
### Prefer Primitive Key Values
React stringifies keys internally. Using a primitive (string or number) avoids extra object allocation and ensures predictable comparison behavior.
### Handling Lists Without Natural IDs
When you don't have a natural ID:
1. **Use the `useId` hook** (React 18+) to generate a stable, globally unique prefix, then combine it with an index that is stable for that render cycle.
```tsx
import {useId} from 'react';
function RandomItemList({items}: {items: string[]}) {
const idPrefix = useId(); // stable across renders
return (
{items.map((item, i) => (
- {item}
// ✅ deterministic key
))}
);
}
```
2. **Transform data upstream** to include a deterministic ID before it reaches the component.
## Working with React.Children.toArray
The `React.Children.toArray` helper clones each child and automatically assigns a key if none is provided, using the child's original key or its position. This is useful when manipulating children (e.g., filtering, reversing) while preserving keys.
```tsx
function ReversedList({children}: {children: React.ReactNode}) {
const normalized = React.Children.toArray(children);
const reversed = normalized.slice().reverse(); // preserves keys
return <>{reversed};
}
/* Usage */