Why the key Prop Matters When Mapping Lists in React

Why the key Prop Matters When Mapping Lists in React

The key prop looks like a minor detail, but it is one of the most misunderstood parts of React. Getting it wrong causes bugs that are hard to trace.

What Keys Do

Keys tell React which elements in a list correspond to which items across re-renders. When the list changes, React uses keys to match old elements to new ones and update only what is necessary.

Why Index Keys Break

Using the array index as a key seems to work, but it breaks when the list is reordered, filtered, or items are inserted in the middle. The index no longer points to the same item, so React reuses the wrong elements.

The Result of Wrong Keys

Symptoms include inputs showing the wrong data after reordering, animations glitching, and component state attaching to the wrong item. These bugs are subtle because the code looks correct.

What Makes a Good Key

A good key is stable across re-renders and unique among siblings. The best key is a unique id from your data, like a database id. Avoid keys derived from the array index for dynamic lists.

Keys Must Be Unique Among Siblings

Keys do not need to be globally unique, only unique among siblings in the same list. Two different lists can reuse the same key values without issue.

Where the Key Goes

The key goes on the outermost element you return for each item. If you extract an item into a component, put the key on that component in the parent's map, not on an element inside the child.

The Takeaway

Keys are React's way of tracking list items across renders. Use stable, unique ids from your data, never the index for dynamic lists, and put the key on the right element. Doing this prevents a whole class of subtle bugs.