Use Stable Keys for List Items

Why this matters

React uses the key prop to identify which items in a list have changed, moved, or been removed. When keys are missing or unstable (like array indexes), React cannot efficiently reconcile the old and new lists.

The consequences are concrete: if a user is typing into an input inside a list item and the list re-orders, React will keep the input's DOM node attached to the wrong item. The user sees their text jump to a different row. Controlled inputs lose focus. Animations restart. Transitions break.

Using array indexes as keys is almost as bad as no keys at all — when items are inserted, deleted, or reordered, the indexes shift and React re-mounts components that didn't actually change.

The rule

Every element returned from .map() in JSX must have a key prop set to a value that is:

1. Stable — does not change between renders for the same item
2. Unique — no two siblings share the same key
3. Derived from data — typically item.id, not the array index

Bad example

function TaskList({ tasks }: { tasks: Task[] }) {
  return (
    <ul>
      {tasks.map((task, index) => (
        // BAD: using array index as key
        <li key={index}>
          <input defaultValue={task.title} />
          <span>{task.status}</span>
        </li>
      ))}
    </ul>
  );
}

Good example

function TaskList({ tasks }: { tasks: Task[] }) {
  return (
    <ul>
      {tasks.map((task) => (
        // GOOD: stable, unique ID from the data
        <li key={task.id}>
          <input defaultValue={task.title} />
          <span>{task.status}</span>
        </li>
      ))}
    </ul>
  );
}

How to detect

Search for .map() calls in JSX that use the index parameter as key:

grep -n "key={index}" --include="*.tsx" --include="*.ts" -r src/
grep -n "key={i}" --include="*.tsx" --include="*.ts" -r src/

Also look for .map() calls where no key prop is present at all — React will warn in development but the code still compiles.

Remediation

1. Check if the data has a unique identifier (id, slug, uuid)
2. Use that identifier as the key: key={item.id}
3. If no natural ID exists, generate one when the data is created (not during render)
4. Array index is acceptable only for truly static lists that never reorder, filter, or change

References

• React docs: Rendering Lists — Keys
• React docs: Why does React need keys?
• Robin Pokorny: Index as a key is an anti-pattern