react-key-prop

Original：🇺🇸 English

Translated

Guides proper usage of the key prop in React lists. Use this skill when rendering lists, mapping arrays to components, or troubleshooting list-related state bugs.

2installs

Sourceflpbalada/my-opencode-config

Added on2026-02-24

NPX Install

npx skill4agent add flpbalada/my-opencode-config react-key-prop

SKILL.md Content

View Translation Comparison →

React: Key Prop Best Practices

Core Principle

Use stable, unique IDs from your data. Never use array index for dynamic lists.

The

key

prop provides stable identity to list elements during React's reconciliation process.

When to Use What

Use Data IDs (Preferred)

Always use unique, stable identifiers directly from your data:

jsx

// ✅ Correct
{todos.map((todo) => (
  <li key={todo.id}>{todo.text}</li>
))}

Ideal keys are:

Unique - No two items share the same key
Stable - Never changes during component lifetime
Predictable - Directly tied to the data item

Generate IDs on Data Load

When data lacks IDs, create them once when receiving data:

jsx

import { nanoid } from 'nanoid';

useEffect(() => {
  fetch('/api/items')
    .then(res => res.json())
    .then(data => {
      const itemsWithIds = data.map(item => ({
        ...item,
        _tempId: nanoid() // Stable ID generated once
      }));
      setItems(itemsWithIds);
    });
}, []);

When Index Is Acceptable (Rare)

Index as key is acceptable ONLY when ALL conditions are met:

List is absolutely static
Items never added/removed (except at the end)
Order never changes
Items have no internal state

Anti-Patterns to Avoid

Never Generate Keys During Render

jsx

// ❌ WRONG: Creates new key every render
{items.map(item => (
  <li key={Math.random()}>{item.name}</li>
))}

This forces React to destroy and recreate all components on every render.

Don't Use Index for Dynamic Lists

jsx

// ❌ WRONG for dynamic lists
{items.map((item, index) => (
  <li key={index}>{item.name}</li>
))}

Index fails when:

Items are added/removed from beginning or middle
List order changes (sorting, filtering)
Items have internal state (like form inputs)

The bug: Index represents position, not data identity. When positions change but indexes stay the same, React incorrectly "mutates" existing components instead of creating new ones, causing state mismatch.

Don't Use

useId()

for List Keys

React's

useId()

hook is for accessibility (linking labels to inputs), not for generating list keys.

Quick Reference

DO

Always use
```
key
```
when rendering lists
Prefer unique, stable
```
id
```
from your data
Generate IDs once at data load time (
```
nanoid
```
/
```
uuid
```
)

DON'T

Never generate
```
key
```
during render (
```
Math.random()
```
,
```
Date.now()
```
)
Avoid
```
index
```
as
```
key
```
for dynamic lists
Don't use
```
useId()
```
for list keys