Rendering lists

From an array of data to a list on the page

Most of what a shop page shows comes from lists: products, cart items, orders, reviews. The data usually arrives as an array of objects, and React has no special loop for showing it. You turn the array of data into an array of JSX elements with JavaScript's map, and React shows that array. The result is live under the code:

1const products = [2  { id: "tea", name: "Tea", price: 3 },3  { id: "cake", name: "Cake", price: 4 },4  { id: "lemonade", name: "Lemonade", price: 2 },5];6 7export default function App() {8  const items = products.map((product) => (9    <li key={product.id}>10      {product.name}: ${product.price}11    </li>12  ));13  return <ul>{items}</ul>;14}

Lines 1 to 5 are the data: three product objects, each with an id, a name, and a price. Line 8 calls products.map, which calls the arrow function once for each product and collects what it gives back into a new array. The function gives back one <li> (lines 9 to 11), so items holds three elements. Line 13 puts the whole array between curly braces, and React shows each element in order: Tea: $3, Cake: $4, and Lemonade: $2.

The key on line 9 is the one new thing. It gives each <li> a name that stays with its product: "tea", "cake", "lemonade". React uses it to tell the items apart when the list changes. Most of this lesson is about why that matters.

Press Edit & run and add a product after line 4: { id: "coffee", name: "Coffee", price: 5 },. A fourth item appears. You changed the data, and the list followed.

map: one component for each item

Real lists show more than a line of text per item, so the map usually gives back a component. Here each product becomes a ProductCard:

1const products = [2  { id: "tea", name: "Tea", price: 3 },3  { id: "cake", name: "Cake", price: 4 },4  { id: "lemonade", name: "Lemonade", price: 2 },5];6 7function ProductCard({ name, price }) {8  return (9    <li className="card">10      <h3>{name}</h3>11      <p>${price}</p>12    </li>13  );14}15 16export default function App() {17  return (18    <ul className="shelf">19      {products.map((product) => (20        <ProductCard key={product.id} name={product.name} price={product.price} />21      ))}22    </ul>23  );24}

Lines 7 to 14 define ProductCard. It takes name and price as props and returns one card as an <li>. Line 19 maps over the products, and line 20 gives back one <ProductCard> for each, with the product's name and price as props. The styles.css tab lays the cards out side by side. The result shows three cards: Tea, Cake, and Lemonade.

Look at where the key is: on line 20, on <ProductCard> inside the map, not on the <li> inside ProductCard. The key belongs on the element the map gives back, because those elements are the items of the list. Inside ProductCard, the <li> has no siblings to be told apart from.

Line 19's arrow function has round brackets after the =>: it gives back the JSX inside them. With curly braces instead, the body is a block of statements, and it gives back nothing unless it says return. A map that gives back nothing makes an array of undefined, and the list comes out empty, with no error. Exercise 2 shows that bug.

Sometimes each item needs more than one element, like a term and its description in a <dl>. Wrap them in a Fragment. The short <>…</> can't take a key, so write <Fragment>:

1import { Fragment } from "react";2 3const drinks = [4  { id: "tea", name: "Tea", about: "Hot, with lemon or milk." },5  { id: "lemonade", name: "Lemonade", about: "Cold, with fresh mint." },6];7 8export default function App() {9  return (10    <dl>11      {drinks.map((drink) => (12        <Fragment key={drink.id}>13          <dt>{drink.name}</dt>14          <dd>{drink.about}</dd>15        </Fragment>16      ))}17    </dl>18  );19}

Line 1 imports Fragment from react. Line 12 wraps each drink's <dt> and <dd> (lines 13 and 14) in a <Fragment key={drink.id}>. The Fragment adds nothing to the page: the <dl> holds the four elements directly, and the result shows each drink with its description under it.

filter and sort before you map

To show only some items, pick them first with filter, then map what's left. Here one array of products makes two parts of the page:

1const products = [2  { id: "tea", name: "Tea", stock: 5 },3  { id: "cake", name: "Cake", stock: 0 },4  { id: "lemonade", name: "Lemonade", stock: 2 },5  { id: "coffee", name: "Coffee", stock: 0 },6];7 8export default function App() {9  const available = products.filter((product) => product.stock > 0);10  const soldOut = products.filter((product) => product.stock === 0);11 12  return (13    <>14      <h3>Available ({available.length})</h3>15      <ul>16        {available.map((product) => (17          <li key={product.id}>{product.name}</li>18        ))}19      </ul>20      {soldOut.length > 0 && (21        <p>Sold out: {soldOut.map((product) => product.name).join(", ")}</p>22      )}23    </>24  );25}

Line 9 keeps the products with stock > 0, and line 10 the ones with none. Neither changes products: filter gives back a new array. Line 14 shows how many are available, and lines 16 to 18 map them to list items: Tea and Lemonade. Line 20 is the conditional rendering from the last lesson: the sold-out line shows only when there is something sold out.

Line 21 maps too, but to strings, not elements, and join(", ") turns them into one string: Sold out: Cake, Coffee. One string isn't a list of elements, so it needs no keys. Press Edit & run and change Cake's stock on line 3 to 1: Cake moves into the list, and the heading says Available (3).

To change the order, sort a copy. sort() sorts the array you call it on, in place, and your data should stay as it came (the Keeping components pure lesson explains why). Use toSorted, which gives back a sorted new array, or copy first with [...products].sort(…):

1const products = [2  { id: "tea", name: "Tea", price: 3 },3  { id: "cake", name: "Cake", price: 4 },4  { id: "lemonade", name: "Lemonade", price: 2 },5];6 7export default function App() {8  const sorted = products.toSorted((a, b) => a.price - b.price);9  return (10    <ol>11      {sorted.map((product) => (12        <li key={product.id}>13          {product.name}: ${product.price}14        </li>15      ))}16    </ol>17  );18}

Line 8 makes sorted: the products by price, lowest first. a.price - b.price is below zero when a is cheaper, which puts a first. Line 11 maps the sorted copy, and the result reads Lemonade: $2, Tea: $3, Cake: $4. products itself still starts with Tea.

Why keys matter: which element is which

When the data changes, React calls your component again and gets a new list of elements. It doesn't throw the old page away: it works out which new element is which old one, and keeps those DOM elements, changing only what differs. For a list, the key is how it matches them. An element with the same key as before, and the same type, like <li>, is "the same item": React keeps its DOM element and anything inside it. A key that's new gets a new element, and an old key that's gone has its element removed. This matching is called reconciliation; Reconciliation and the diffing algorithm, in the course's last stage, follows it through React's own code.

You can't see that matching while the list only shows text. You can see it once each row holds something of its own, like a box you typed into. This cart uses each item's position, index, as its key, with a bug on purpose:

1import { useState } from "react";2 3const cart = [4  { id: "tea", name: "Tea" },5  { id: "cake", name: "Cake" },6  { id: "lemonade", name: "Lemonade" },7];8 9export default function App() {10  const [items, setItems] = useState(cart);11 12  function remove(id) {13    setItems(items.filter((item) => item.id !== id));14  }15 16  return (17    <ul>18      {items.map((item, index) => (19        <li key={index}>20          {item.name}21          <input placeholder="Gift note" />22          <button onClick={() => remove(item.id)}>Remove</button>23        </li>24      ))}25    </ul>26  );27}

Line 10 keeps the cart in state, a value React remembers for the component (state gets its own lesson, State: a component's memory). remove on lines 12 to 14 makes a new array without one item. Line 18 maps the items with their position, index, and line 19 uses it as the key. Each row has the name (line 20), a box for a gift note (line 21), and a Remove button (line 22). The styles.css tab lines the rows up.

Type for Asha in Tea's box, then click Remove on Tea's row. Tea is gone, but for Asha now sits next to Cake. Here is what React saw. Before, the keys were 0, 1, and 2, for Tea, Cake, and Lemonade. After, the keys are 0 and 1, for Cake and Lemonade. Key 0 is still there, so React kept that <li>, with its box and your text, and changed its name from Tea to Cake. Key 1 changed from Cake to Lemonade. Key 2 is gone, so React removed the last row. The text in a box belongs to the box's element, and React never had a reason to touch it.

Now press Edit & run, change line 19 to <li key={item.id}>, and try again. This time the keys are tea, cake, and lemonade. After the removal, tea is gone, so React removes Tea's row, with your note. Cake and Lemonade keep their own rows.

The playground below makes the matching visible. It numbers every <li> the first time React puts it on the page, so a number that stays is the same element. Pick a key, press Fill in notes, and then change the list.

1function NoteList({ items }) {2  return (3    <ul>4      {items.map((item, index) => (5        <li key={index}>6          {item.name}7          <input placeholder="Gift note" />8        </li>9      ))}10    </ul>11  );12}

With key={index}, press Remove first: #1 and #2 stay and change their names, #3 goes, and "Tea's note" ends up next to Cake. Press Reset, pick key={item.id}, fill in the notes, and press Reverse: the numbers travel with their items, notes and all, because React moves the elements instead of relabeling them. Add to top shows the same: with the index, every row gets a new name and a new #4 appears at the end; with the id, only the new item gets a new element.

The same goes for anything a row keeps for itself: the text in a box, whether a checkbox is ticked, where the keyboard focus is, and a component's own state, as Preserving and resetting state shows later. The key decides which item they belong to.

What React says when a key is missing

Leave the key out, and React still shows the list, matching the items by position, the same as the index. It also warns you:

1const products = ["Tea", "Cake", "Lemonade"];2 3export default function App() {4  return (5    <ul>6      {products.map((name) => (7        <li>{name}</li>8      ))}9    </ul>10  );11}

Line 7 has no key. The list shows, and the console under the result shows React's warning:

Each child in a list should have a unique "key" prop.

Check the render method of `App`. See https://react.dev/link/warning-keys for more information.

"Each child in a list" means each element in the array. The second line names the component whose list it is, App, so you know where to look. Add key={name} on line 7, since every name in this list is different, and the warning goes. React prints its warnings while you develop; a production build leaves them out.

Choosing a good key

A good key has two properties:

• Unique among its siblings. No two items in the same list share it. Two different lists can use the same keys.
• The same on every render. It stays with its item, whatever position the item moves to.

The best keys come with the data. Products, orders, and users from a server usually have an id from the database. When there isn't one, look for a field or a set of fields that together are unique. A name alone often isn't:

1const products = [2  { shop: "Corner Café", name: "Tea" },3  { shop: "Corner Café", name: "Cake" },4  { shop: "Station Kiosk", name: "Tea" },5];6 7export default function App() {8  return (9    <ul>10      {products.map((product) => (11        <li key={product.name}>12          {product.name} from {product.shop}13        </li>14      ))}15    </ul>16  );17}

Lines 2 and 4 are both Tea, from different shops, so line 11 gives two items the key Tea. The list still shows all three, but React warns in the console:

Encountered two children with the same key, `Tea`. Keys should be unique so that components maintain their identity across updates.

Its full text goes on to say that a repeated key can make items appear twice or go missing when the list changes. Press Edit & run and change line 11 to <li key={product.shop + product.name}>: the shop and the name together are unique, and the warning goes.

For items made in the browser, like a line the reader adds to a list, make the id when you create the item, in the code that adds it: a counter, or crypto.randomUUID(). Never make it in the map. key={Math.random()} or key={crypto.randomUUID()} written there runs again on every render, so every key is new every time:

Try it in the playground above: pick key={Math.random()}, fill in the notes, and press any button. Every number changes, and every note is gone: React found no matching key, removed every row, and made new ones.

The index is fine in one case: a list that never changes order, never has items added or removed anywhere but the end, and holds nothing of its own, like a fixed list of footer links. The cart in Why React? only adds and removes at the end, which is why its key={index} worked.

One more rule: key is for React, not for your component. React takes it out of the props, so a component never receives it. If a component needs the id, pass it again under another name:

1const products = [2  { id: "tea", name: "Tea" },3  { id: "cake", name: "Cake" },4];5 6function CartRow({ id, name }) {7  return (8    <li>9      {name} <small>item {id}</small>10    </li>11  );12}13 14export default function App() {15  return (16    <ul>17      {products.map((product) => (18        <CartRow key={product.id} id={product.id} name={product.name} />19      ))}20    </ul>21  );22}

Line 18 gives each CartRow the same value twice: as key, for React, and as id, for the component. Line 6 reads id, and line 9 shows it: Tea item tea. Press Edit & run and change id to key on lines 6 and 9. The ids disappear, and the console says CartRow: `key` is not a prop. Trying to access it will result in `undefined` being returned.

How to read this table: each row is a kind of key, with the two questions a good key must pass, and the verdict.

A shopping list that keeps its numbers

Here is everything together: a shopping list where you add items, set how many of each you need, sort, and remove. Add Bread, set Tea to 3, then press Sort A to Z.

1import { useState } from "react";2 3let nextId = 3;4 5export default function App() {6  const [items, setItems] = useState([7    { id: 1, name: "Tea" },8    { id: 2, name: "Cake" },9  ]);10  const [name, setName] = useState("");11 12  function add() {13    if (name.trim() === "") return;14    setItems([...items, { id: nextId++, name: name.trim() }]);15    setName("");16  }17 18  function remove(id) {19    setItems(items.filter((item) => item.id !== id));20  }21 22  function sortByName() {23    setItems(items.toSorted((a, b) => a.name.localeCompare(b.name)));24  }25 26  return (27    <>28      <input29        value={name}30        onChange={(event) => setName(event.target.value)}31        placeholder="Add an item"32      />33      <button onClick={add}>Add</button>34      <button onClick={sortByName}>Sort A to Z</button>35      <ul>36        {items.map((item) => (37          <li key={item.id}>38            {item.name}39            <input type="number" defaultValue={1} min={1} aria-label={`How many ${item.name}`} />40            <button onClick={() => remove(item.id)}>Remove</button>41          </li>42        ))}43      </ul>44      {items.length === 0 && <p>Your list is empty.</p>}45    </>46  );47}

The list is sorted, Bread, Cake, Tea, and Tea still needs 3. Each number box is an <input> that keeps what you typed (line 39), and each row's key is the item's id (line 37), so React moved the rows instead of relabeling them.

• Line 3 starts a counter, and line 14 gives every new item the next number as its id, once, when add creates it.
• Line 19 removes an item by its id with filter, and line 23 sorts a copy with toSorted and localeCompare, which compares text the way a dictionary does.
• Line 44 shows a message once the list is empty: conditional rendering again.

Press Edit & run and change line 37 to <li key={index}> and line 36 to {items.map((item, index) => (. Then do the same steps: after the sort, the 3 sits next to Bread, in the first row, where Tea used to be.

Common mix-ups

• "Keys are only there to make lists faster." No. They decide which element belongs to which item. A wrong key puts typed text, ticks, and state next to the wrong item.
• "key={index} fixes the warning, so it's fine." It only silences the warning. Without a key, React already uses the index, so the bug stays the same.
• "Keys must be unique on the whole page." No. Only among siblings, the items of one list. Two lists can both use tea.
• "Math.random() makes a good unique key." It's unique, but it's new on every render, so React makes every element again.
• "A component can read its own key." No. props.key is undefined. Pass the value as another prop too, like id.
• "The key goes on the element inside the component." No. It goes on the element the map gives back, like <ProductCard key={product.id} />.

Practice exercises

Each exercise shows its result under the code, or when you press Edit & run. Change the code, and the result updates as you type. For the first one, answer before you run anything.

const products = [
  { id: "tea", name: "Tea", price: 3 },
  { id: "cake", name: "Cake", price: 4 },
  { id: "lemonade", name: "Lemonade", price: 2 },
  { id: "coffee", name: "Coffee", price: 5 },
];

export default function App() {
  return (
    <ul>
      {products
        .filter((product) => product.price < 4)
        .map((product) => (
          <li key={product.id}>{product.name}</li>
        ))}
    </ul>
  );
}

1const products = [2  { id: "tea", name: "Tea", price: 3 },3  { id: "cake", name: "Cake", price: 4 },4  { id: "lemonade", name: "Lemonade", price: 2 },5  { id: "coffee", name: "Coffee", price: 5 },6];7 8export default function App() {9  return (10    <ul>11      {products12        .filter((product) => product.price < 4)13        .map((product) => (14          <li key={product.id}>{product.name}</li>15        ))}16    </ul>17  );18}

1const products = [2  { id: "tea", name: "Tea" },3  { id: "cake", name: "Cake" },4  { id: "lemonade", name: "Lemonade" },5];6 7export default function App() {8  return (9    <ul>10      {products.map((product) => {11        <li key={product.id}>{product.name}</li>;12      })}13    </ul>14  );15}

1const products = [2  { id: "tea", name: "Tea" },3  { id: "cake", name: "Cake" },4  { id: "lemonade", name: "Lemonade" },5];6 7export default function App() {8  return (9    <ul>10      {products.map((product) => (11        <li key={product.id}>{product.name}</li>12      ))}13    </ul>14  );15}

1const products = [2  { id: "tea", name: "Tea" },3  { id: "cake", name: "Cake" },4  { id: "lemonade", name: "Lemonade" },5];6 7export default function App() {8  return (9    <ul>10      {products.map((product) => (11        <li>{product.name}</li>12      ))}13    </ul>14  );15}

1const products = [2  { id: "tea", name: "Tea" },3  { id: "cake", name: "Cake" },4  { id: "lemonade", name: "Lemonade" },5];6 7export default function App() {8  return (9    <ul>10      {products.map((product) => (11        <li key={product.id}>{product.name}</li>12      ))}13    </ul>14  );15}

1const products = [2  { id: "tea", name: "Tea", stock: 5 },3  { id: "cake", name: "Cake", stock: 0 },4  { id: "lemonade", name: "Lemonade", stock: 2 },5];6 7export default function App() {8  return (9    <ul>10      {products.map((product) => (11        <li key={product.id}>12          {product.name} ({product.stock} left)13        </li>14      ))}15    </ul>16  );17}

1const products = [2  { id: "tea", name: "Tea", stock: 5 },3  { id: "cake", name: "Cake", stock: 0 },4  { id: "lemonade", name: "Lemonade", stock: 2 },5];6 7export default function App() {8  return (9    <ul>10      {products11        .filter((product) => product.stock > 0)12        .map((product) => (13          <li key={product.id}>14            {product.name} ({product.stock} left)15          </li>16        ))}17    </ul>18  );19}

1import { useState } from "react";2 3const cart = [4  { id: "tea", name: "Tea" },5  { id: "cake", name: "Cake" },6  { id: "lemonade", name: "Lemonade" },7];8 9export default function App() {10  const [items, setItems] = useState(cart);11 12  return (13    <>14      <button onClick={() => setItems(items.toReversed())}>Reverse</button>15      <ul>16        {items.map((item, index) => (17          <li key={index}>18            {item.name}19            <input placeholder="Gift note" />20          </li>21        ))}22      </ul>23    </>24  );25}

1import { useState } from "react";2 3const cart = [4  { id: "tea", name: "Tea" },5  { id: "cake", name: "Cake" },6  { id: "lemonade", name: "Lemonade" },7];8 9export default function App() {10  const [items, setItems] = useState(cart);11 12  return (13    <>14      <button onClick={() => setItems(items.toReversed())}>Reverse</button>15      <ul>16        {items.map((item) => (17          <li key={item.id}>18            {item.name}19            <input placeholder="Gift note" />20          </li>21        ))}22      </ul>23    </>24  );25}

1const orders = [2  { id: 7, items: ["Tea", "Cake"] },3  { id: 8, items: ["Tea", "Lemonade", "Cake"] },4];5 6export default function App() {7  return (8    <>9      {/* For each order: a heading, Order 7, and a list of its items. */}10    </>11  );12}

1const orders = [2  { id: 7, items: ["Tea", "Cake"] },3  { id: 8, items: ["Tea", "Lemonade", "Cake"] },4];5 6export default function App() {7  return (8    <>9      {orders.map((order) => (10        <section key={order.id}>11          <h3>Order {order.id}</h3>12          <ul>13            {order.items.map((item) => (14              <li key={item}>{item}</li>15            ))}16          </ul>17        </section>18      ))}19    </>20  );21}

Check your understanding

For each key question, ask what the key was before a change and what it is after. Press Edit & run on a question's code to check your answer.

Key takeaways

• Turn an array of data into an array of elements with map, and put it in curly braces. Use filter and toSorted first to pick and order the items, without changing the data.
• Give each element in the array a key, on the element the map gives back. Use <Fragment key> for several elements per item.
• React matches the new list to the old one by key: same key, same element, with what was typed into it. Without keys it matches by position, and warns.
• A good key is unique among its siblings and the same on every render: an id from the data, or one made when the item is created. Not the index in a list that changes order, and never Math.random().
• key isn't a prop. If the component needs the id, pass it again as another prop.

Coming next: Keeping components pure. It shows why a component should only calculate while it renders, and how StrictMode helps you catch the ones that don't.