The importance of component keys in React.js

TL;DR Use unique and constant keys when rendering dynamic children, or expect strange things to happen.

One of the tricky aspects I've found during the few weeks I've been using React.js is to understand the key property you're expected to pass to a component when it's part of an array of children. It's not that you have to specify this property, things will work most of the time apart from getting this warning on the console:

Each child in an array should have a unique "key" prop. Check the render method of undefined. See http://fb.me/react-warning-keys for more information.

By reading the linked documentation it can be easy to not see the implications of this affirmation:

When React reconciles the keyed children, it will ensure that any child with key will be reordered (instead of clobbered) or destroyed (instead of reused).

At first it looked to me it was all about performance but, as Paul O’Shannessy pointed, it's actually about identity.

The key here is to understand not everything in the DOM has a representation in React "Virtual DOM" and, because direct manipulations of the DOM (like a user changing an <input> value or a jQuery plugin listening an element) are unnoticed by React, not using unique and constant keys will end up with React recreating the DOM node of a component when the key is not constant (and losing any untracked state in the node) or reusing a DOM node to render another component when the key is not unique (and tying its state to this other component).

Here you have a live demo showing how awful the results are:

http://jsfiddle.net/frosas/S4Dju/

Just add an item, change it, add more items and see what happens.