Why React Keys Matter: Preventing Bugs in Dynamic Lists

We know that React elements can have a special

key

prop that is used internally by React, not by developers. When dynamically creating React elements that contain an uncertain number or order of child elements, you must provide this unique

key

prop.

If you have code like:

<code>const UserList = props => (
  <div>
    <h3>User List</h3>
    {props.users.map(u => <div>{u.id}:{u.name}</div>)}  // no key
  </div>
);</code>

React will print a warning in the console:

<code>Warning: Each child in an array or iterator should have a unique "key" prop. Check the render method of `App`. See https://fb.me/react-warning-keys for more information.</code>

You must provide a unique

key

for each element in the array, for example:

<code>const UserList = props => (
  <div>
    <h3>User List</h3>
    {props.users.map(u => <div key={u.id}>{u.id}:{u.name}</div>)}  // key provided
  </div>
);</code>

Why? When a component's props change, its render method is called again and the component re‑renders. If the

users

prop of

UserList

changes, React must re‑render the container

<div>

, the header

<h3>

, and each user

<div>

inside the array.

For the array elements, React needs to decide whether to create a new DOM node or update an existing one. Consider these scenarios:

Updating an existing user's age:

[{name: 'Zhang San', age: 20}] → [{name: 'Zhang San', age: 21}]

. Only the age changes, so the element can be updated without recreation.

Adding a new user:

[{name: 'Zhang San'}] → [{name: 'Zhang San'}, {name: 'Li Si'}]

. A new element must be inserted for the new user.

Replacing one user with another:

[{name: 'Zhang San'}] → [{name: 'Li Si'}]

. Without a stable key, React cannot know whether to delete the old element and create a new one or simply replace the content.

If you rely on element order alone, confusing cases arise, such as swapping two users in the array. Providing a unique key (e.g., the user ID) lets React compare the keys before and after the update: identical keys mean an update, different keys trigger destruction of the old element and creation of a new one.

Only elements inside arrays need explicit keys because elements outside arrays appear in a fixed position in the argument list of

React.createElement

, which serves as an implicit key. The Babel‑transformed code makes this clear:

<code>// before JSX compilation
const element = (
  <div>
    <h3>example</h3>
    {[<p key={1}>hello</p>, <p key={2}>world</p>]}
  </div>
);

// after compilation
"use strict";

var element = React.createElement(
  "div",
  null,
  React.createElement("h3", null, "example"),
  [
    React.createElement("p", { key: 1 }, "hello"),
    React.createElement("p", { key: 2 }, "world")
  ]
);
</code>

Because non‑array elements always occupy the same position in the

createElement

call, they have a natural, stable key.

Side note When you first learn React, you may wonder why JSX does not support an if statement for conditional rendering and forces you to use the ternary operator. React needs a null placeholder to keep the element's position in the tree.

In a more complex scenario, such as a

UserDashboard

component that receives only basic user info via props and fetches detailed data asynchronously, you might have a single

UserDashboard

on the page while switching the target user by clicking a

UserList

entry. The prop change triggers the full update lifecycle (

componentWillReceiveProps

,

shouldComponentUpdate

,

componentWillUpdate

,

componentDidUpdate

), forcing you to manually clean up pending requests, reset state, and handle refs, which quickly becomes tangled.

The solution is to give the

UserDashboard

component a unique

key

based on the user ID. When the target user changes, the key also changes, causing React to unmount the previous component and mount a fresh one. Cleanup can then be performed in

componentWillUnmount

, and you no longer need to manually reset state or cancel requests during an update.

Performance concerns are minimal: as long as user switches are not extremely frequent, the overhead of unmounting and remounting is negligible compared to the benefits of a clean lifecycle.

Therefore, for any complex stateful component that corresponds to a specific object, you should almost always provide a stable

key

(as long as the key does not change too often). This enables React to destroy and recreate components at the right moments, keeping component lifecycles healthy.

Side note When using react-router , you often need to assign a key to route components. Since you cannot directly pass props to a route component, you can wrap the creation in a custom createElement function:

<code>class App extends Component {
  static createElement = (Component, ownProps) => {
    const { userId } = ownProps.params;
    switch (Component) {
      case UserDashboard:
        return <Component key={userId} {...ownProps}/>;
      default:
        return <Component {...ownProps}/>;
    }
  };
  render() {
    return (
      <Provider store={store}>
        <Router createElement={App.createElement}
                history={syncHistoryWithStore(hashHistory, store)}>
          <Route path="/" component={Home}>
            <IndexRoute component={Index}/>
            <Route path="users/:userId" component={UserDashboard}/>
          </Route>
        </Router>
      </Provider>
    );
  }
}
</code>

(End of article)