Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Props and Attributes

React key prop

Reference for the React key prop: how keys identify list items, why index keys cause bugs, how a key resets component state, and the rules for valid keys.

key is a special prop that tells React which element is which between renders. When you render a list, React uses keys to match each item in the new list with the same item in the previous one, so it can keep that item's DOM node and component state, move it when the order changes, and destroy it only when it really disappears.

A key is not passed to your component as a prop; it is consumed by React. It only has to be unique among siblings, not across the page. Every element created inside a .map() call needs one.

JSX
<ul>
  {todos.map((todo) => (
    <li key={todo.id}>{todo.text}</li>
  ))}
</ul>

Try it

Index keys versus stable keys
Resetting state with a key

Syntax

JSX
<Component key={value} />
Name Description
key A string or number that is unique among the element's siblings and does not change between renders for the same logical item. Other values are converted to strings.

Returns: nothing. key is read by React and is not available as props.key. To pass the same value to a child, use a second prop with another name (id).

Errors: a missing key in a list logs Each child in a list should have a unique "key" prop. Two siblings with the same key log a duplicate-key warning, and the second one may be dropped or duplicated on updates.

Usage notes

  • Use data ids. Keys should come from the data (a database id, a slug) and stay the same for the same item across renders and reorders.
  • Generate ids when the data is created, not while rendering. key={Math.random()} or crypto.randomUUID() inside the render makes every key new on every render, so React destroys and recreates all the items each time and form state is lost.
  • Index keys are acceptable only for static lists that are never reordered, filtered, inserted into or removed from. In the first example, the index-keyed list leaves the typed note in the first box after the first item is removed, so it now looks like it belongs to Bo.
  • Keys reset state. When a component's key changes, React throws away that instance (state, refs, effects, DOM) and mounts a new one. This is the cleanest way to reset a form or a detail pane when the selected item changes, without an effect that copies props into state.
  • Keys work outside lists. You can give any element a key to force a remount, including a single element or a component with no siblings.
  • Fragments need keys when produced by .map(). Use the long form <Fragment key={id}>, since the <> shorthand cannot take a key. See <Fragment>.
  • Keys are scoped to the parent. The same key may appear in two different lists. They only have to differ among siblings.
  • Do not put the key on the inner element. It belongs on the outermost element returned by .map(), not on a child inside the component you are rendering.
  • Keys and performance. Stable keys let React move existing nodes instead of rebuilding them, and avoid unnecessary child re-renders when combined with memo.