Keys & lists

React · Reference cheat sheet

📋 Overview

When rendering lists, each sibling needs a stable key so React can match items across updates. Keys should identify the item (id), not its position. Correct keys preserve state and avoid buggy remounts.

🔧 Core concepts

• Purpose — identity for reconciliation, not display.
• Stable — same item → same key across renders.
• Unique among siblings — not globally unique required.
• Avoid index — unless the list is static and never reorders.
• Reset state — changing key on a component remounts it.

💡 Examples

type Todo = { id: string; text: string; done: boolean };

export function TodoList({ todos }: { todos: Todo[] }) {
  return (
    <ul>
      {todos.map((todo) => (
        <li key={todo.id}>
          <TodoRow todo={todo} />
        </li>
      ))}
    </ul>
  );
}

Remount to reset form:

<Editor key={selectedId} documentId={selectedId} />

Fragments with keys:

{items.map((item) => (
  <Fragment key={item.id}>
    <dt>{item.term}</dt>
    <dd>{item.description}</dd>
  </Fragment>
))}

⚠️ Pitfalls

• key=\{index\} with insert/reorder/delete → wrong state on inputs.
• Random keys (Math.random()) every render → remount thrash.
• Using array index after sorting/filtering.
• Putting key on the wrong element (must be on the outermost mapped element).

🔗 Related

• fragments.md — keyed fragments
• conditional_rendering.md — list empty states
• jsx.md — expressions
• performance.md — list virtualization
• memo.md — row memoization