Lists and Keys in React: Why Keys Matter

Jun 2, 2026 · 6 min read

← All articles

Rendering a list in React means mapping an array to elements. It's a one-liner — but the key prop React asks for is more important than it looks. (Showing a list only sometimes? Pair this with conditional rendering.)

Rendering a list

function TodoList({ todos }) {
  return (
    <ul>
      {todos.map(todo => (
        <li key={todo.id}>{todo.text}</li>
      ))}
    </ul>
  );
}

Why keys exist

When the list changes, React needs to figure out which items were added, removed, or reordered so it can update the DOM efficiently. The key is the stable identity React uses to match an item across renders. Without good keys, React can update the wrong DOM nodes — losing input focus, mixing up component state, or re-rendering more than necessary.

Don't use the array index

It's tempting to write key={index}, and it works until the list reorders or items are inserted/removed. Then the index no longer points to the same logical item, and React reuses the wrong element. Use a stable id from your data instead:

// risky if the list can change order or length
{items.map((item, index) => <Row key={index} ... />)}

// stable
{items.map(item => <Row key={item.id} ... />)}

Rules for keys

• Keys must be unique among siblings (not globally).
• Keys should be stable — the same item gets the same key every render.
• Keys go on the element returned directly by map, not on a child inside it.
• Keys are a hint for React; they aren't passed to your component as a prop.

Key takeaways

• Keys give list items a stable identity across renders.
• Prefer a real id; avoid the array index for dynamic lists.
• Bad keys cause subtle bugs with focus and component state.

Want the structured path? Explore the React roadmap or browse more articles.