React Key Prop Mistakes That Cause Unnecessary Re-Renders

A genuinely tricky debugging session I was involved in started with a component appearing to lose its internal state unexpectedly whenever a parent list reordered, with the actual root cause tracing back to a key prop mistake that was not immediately obvious from looking at the rendering output alone, only becoming clear once we specifically investigated how React was reconciling these specific list items.

Why Keys Matter for More Than Just Suppressing Console Warnings

Many developers add key props primarily to suppress React’s console warning about missing keys, without fully understanding that keys serve a genuine, functional purpose in React’s reconciliation process — helping React determine which specific elements in a new render correspond to which specific elements from the previous render, particularly important when list order or composition changes between renders.

Without stable, correct keys, React’s default reconciliation behavior can incorrectly match elements between renders, leading to components losing their internal state, unnecessary unmounting and remounting (with associated performance cost), or even displaying incorrect data temporarily during the transition between renders.

The Index-as-Key Problem in Detail

Using array index as a key works correctly only when your list never reorders, filters, or has items inserted/removed from anywhere except the very end. The moment any of these operations occur, index-based keys can cause React to incorrectly associate a different underlying data item with what it believes is the “same” element from the previous render, simply because that element occupies the same index position.

// Index 0 always refers to "whatever is currently first"
// not a stable identity for a specific data item
{items.map((item, index) => (
  <ListItem key={index} data={item} />
))}

If this list reorders, the element at index 0 in the new render is treated by React as “the same element” as whatever was at index 0 previously, even if it actually represents an entirely different underlying data item now, since React’s reconciliation specifically uses the key to determine this correspondence, and index does not reliably track genuine item identity across reordering.

How This Caused the State Loss I Was Debugging

In the specific case I was investigating, each list item contained an expandable section with its own local useState tracking whether it was currently expanded. When the parent list reordered (due to a sort operation), items that had been expanded appeared to randomly lose their expanded state, while different items sometimes appeared expanded that the user had not actually expanded themselves.

The root cause was exactly this index-based key issue — React was preserving component state based on index position rather than actual item identity, meaning after reordering, the component instance that previously corresponded to item A (now at a different index) was being treated as if it now corresponded to whatever item happened to occupy that original index position, carrying over the wrong component’s previous expanded state to the wrong actual data item.

The Fix: Genuinely Stable, Unique Identifiers

Switching from index-based keys to a stable identifier actually belonging to each specific data item (a database ID, a unique field that genuinely identifies that specific item regardless of its current position in the list) resolved this issue directly, since React could now correctly track each item’s actual identity across reordering, correctly preserving the expanded state association with the actual specific item the user had expanded, rather than incorrectly associating it with whatever item happened to occupy the same index position after reordering.

// Stable identity regardless of list position
{items.map((item) => (
  <ListItem key={item.id} data={item} />
))}

A Related Mistake: Using Non-Unique Keys

Beyond index-based keys, using a key value that is not actually unique across your list (perhaps a category field where multiple items share the same category) produces similarly incorrect reconciliation behavior, since React requires genuine uniqueness among sibling keys to correctly track individual item identity, and duplicate keys can cause React to behave unpredictably regarding which specific elements correspond to which underlying data.

If your data does not have an obviously unique field suitable for this purpose, generating a genuinely unique identifier specifically for this purpose (rather than reusing a non-unique existing field purely because it happens to be convenient) avoids this category of issue.

Why Changing Keys Unnecessarily Also Causes Problems

The inverse mistake — using a key that changes even when the underlying item has not genuinely changed identity — causes React to treat what should be the same persistent element as an entirely new one, triggering unnecessary unmounting of the old element and mounting of a “new” one, with associated performance cost and loss of any local component state that should have genuinely persisted across that update.

This can happen if you construct a key from multiple combined fields where one of those fields changes for reasons unrelated to genuine item identity, inadvertently producing a different key value despite the underlying item still being conceptually the same persistent entity.

Verifying Key-Related Issues Through Profiling

Using React DevTools, checking whether components are unmounting and remounting unexpectedly (rather than simply re-rendering with updated props) when you would expect them to persist as the same component instance across a list update can help confirm whether a key-related reconciliation issue is occurring, distinct from other performance issues covered in our other guides that involve components re-rendering but not actually unmounting and remounting incorrectly.

A Quick Reference Summary

What Resolved the Original Debugging Session

Once we identified the index-based key as the actual root cause, switching to each item’s genuine database identifier as the key immediately resolved the state association issue, confirmed through testing the same reordering operation that had previously triggered the incorrect behavior and observing that expanded state now correctly remained associated with the actual specific items users had expanded, regardless of subsequent reordering operations.

Are you experiencing unexpected state loss or behavior in a list component, particularly after reordering or filtering? Describe your situation and I can help you check whether a key-related issue might be the cause.