Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Components and Special Elements

Keyed fragments

How to give a React Fragment a key when a list item renders several sibling elements, why the short <></> syntax cannot do it, and what keys preserve.

When you render a list with map(), React needs a stable key on every item that the callback returns. That is easy when each item is a single element. It gets awkward when one data item should produce two or more sibling elements, such as a <dt> and a <dd> in a description list, or a table row followed by a detail row. You cannot return two bare siblings from the callback, so you wrap them in a fragment, and the fragment is the item that needs the key.

The short syntax <>...</> has no place to put attributes, so it cannot take a key. Use the long form <Fragment key={item.id}> instead. It renders no DOM node of its own; the key is only for React's bookkeeping.

JSX
import { Fragment } from 'react';

{items.map((item) => (
  <Fragment key={item.id}>
    <dt>{item.term}</dt>
    <dd>{item.meaning}</dd>
  </Fragment>
))}

Try it

A description list from data
The key keeps state with its group

Type "hello" into Ada's note and press Reverse order. Ada moves to the bottom and her text moves with her, because React matched the fragments by key and moved the existing components instead of rebuilding them. Replace key={name} with key={index} and the text stays at the top while the names swap under it.

Syntax

JSX
<Fragment key={value}>...</Fragment>
Name Description
key A string or number that is unique among the siblings in the same array and stays the same for the same data item between renders.

Not valid: <key={id}>...</>. The short form has no attribute syntax at all.

Edge cases: a missing key on a fragment returned from map() produces the usual "unique key" warning in development, and React falls back to using the index. Duplicate keys among siblings give another warning and can cause items to be duplicated or dropped during reordering.

Usage notes

  • Put the key on the outermost element returned by the callback. If the callback returns <Fragment key="a"><Row key="b" /></Fragment>, only the fragment's key matters for the list; the inner key is redundant.
  • Use data identity, not position. Database IDs, slugs or other stable values are right. Math.random() creates a new key on every render and remounts everything. An index is acceptable only for static lists that never reorder, filter or insert.
  • A key is not a prop. Inside the component, props.key is not available. If the child needs the value, pass it again under another name.
  • Keys only need to be unique among siblings, not across the whole app. Two different lists can reuse the same ids.
  • Changing a key remounts. Giving the same fragment a new key throws away the subtree state and mounts fresh components. You can use this on purpose to reset a form.
  • If you can, use an element. A <ul> of <li> items needs only a key on each <li>. Reach for a keyed fragment only when you genuinely need several siblings per item.
  • No DOM cost. Fragments add no nodes, so a keyed fragment does not change how the browser lays out the list.