🔑 Keys in React

What Is a Key?

A key is a string or number you attach to each element in a rendered list. It is not passed to your component and it never appears in the DOM. Its single job is to give each item a stable identity that React can recognize from one render to the next.

Think of a coat check. When you hand over your coat you get a numbered ticket. Later you present the ticket and get your coat back — not whichever coat happens to be hanging in that position now. The key is that ticket. Without it, React can only identify items by where they sit in the list (their position), which falls apart the moment the list changes order.

function TeamList({ members }) {
    return (
        <ul>
            {members.map((member) => (
                // member.id is the "coat check ticket" — a durable identity.
                <li key={member.id}>{member.name}</li>
            ))}
        </ul>
    );
}

How Reconciliation Uses Keys

When state changes, your component re-runs and produces a fresh tree of elements. React does not throw away the old DOM and rebuild it — that would be slow and would destroy focus, scroll position, and component state. Instead it runs reconciliation: it compares the new element tree to the previous one and applies the minimal set of DOM changes. For lists, keys are how it lines the two versions up.

Read that carefully: React matches by key first, then by position. When keys are stable ids, an item that merely moved keeps the same key, so React reuses its DOM node and its component state and simply re-positions it. When keys are missing, React falls back to position — item #1 is compared to old item #1 regardless of whether it is really the same thing.

The Index-as-Key Bug

Here is the failure everyone hits once. Consider an editable list where each row has a label and a text input, and a button that inserts a new row at the top. We key by array index.

import { useState } from 'react';

// ❌ BUGGY: keyed by index.
function GuestListBuggy() {
    const [guests, setGuests] = useState([
        { name: 'Alice' },
        { name: 'Bob' },
        { name: 'Carol' },
    ]);

    // Insert a new guest at the FRONT of the list.
    const addAtTop = () =>
        setGuests([{ name: 'NEW' }, ...guests]);

    return (
        <div>
            <button onClick={addAtTop}>Add guest at top</button>
            <ul>
                {guests.map((guest, index) => (
                    <li key={index}>
                        {guest.name}:{' '}
                        {/* Uncontrolled input — its text lives in the DOM node */}
                        <input placeholder="meal preference" />
                    </li>
                ))}
            </ul>
        </div>
    );
}

Try it in your head. You type "vegan" into Alice's input, "none" into Bob's. Now you click Add guest at top. What should happen: a new empty row appears above Alice, and everyone's typed text stays with the right person. What actually happens with index keys:

Why? The new array is [NEW, Alice, Bob, Carol]. Their index keys are now 0, 1, 2, 3. React compares by key: old key=0 (which owned the input containing "vegan") is matched to new key=0, which is NEW. So the DOM input that holds "vegan" is reused for NEW's row. Alice slides to key=1 and inherits Bob's old input ("none"). Every uncontrolled value is off by one. The labels updated because they come from props, but the input state lives in the DOM node React decided to reuse.

The fix: a stable id

// ✅ CORRECT: keyed by a stable id that belongs to the guest.
function GuestListFixed() {
    const [guests, setGuests] = useState([
        { id: 'a', name: 'Alice' },
        { id: 'b', name: 'Bob' },
        { id: 'c', name: 'Carol' },
    ]);

    const addAtTop = () =>
        setGuests([{ id: crypto.randomUUID(), name: 'NEW' }, ...guests]);

    return (
        <div>
            <button onClick={addAtTop}>Add guest at top</button>
            <ul>
                {guests.map((guest) => (
                    // The key follows the guest, wherever they move.
                    <li key={guest.id}>
                        {guest.name}: <input placeholder="meal preference" />
                    </li>
                ))}
            </ul>
        </div>
    );
}

Now Alice's key is "a" whether she is at index 0 or index 1. React matches key="a" to key="a", keeps her exact input node, and simply moves it down. NEW gets a genuinely new key, so React mounts a fresh, empty input for it. Everyone's text stays with the right person.

Rules for Good Keys

A good key is unique among siblings, stable across renders, and predictable (derived from the data, not from render order or randomness).

1. Unique among siblings

// Nested lists: each map has its own sibling scope.
function Catalog({ categories }) {
    return (
        <div>
            {categories.map((category) => (
                <section key={category.id}>
                    <h3>{category.name}</h3>
                    <ul>
                        {category.items.map((item) => (
                            // Only needs to be unique within THIS <ul>.
                            <li key={item.id}>{item.name}</li>
                        ))}
                    </ul>
                </section>
            ))}
        </div>
    );
}

2. Stable across renders

// ❌ New key every render — React remounts every item, every time.
{items.map((item) => (
    <li key={Math.random()}>{item.text}</li>
))}

// ✅ Same key persists across renders.
{items.map((item) => (
    <li key={item.id}>{item.text}</li>
))}

A key generated with Math.random() or Date.now() inside render changes every time, so React thinks every item is new on each render — it unmounts and remounts the whole list, destroying focus and state and killing performance. Generate ids once, when the item is created, and store them in state.

3. Predictable (from the data)

// ❌ Key depends on a counter that resets each render.
let counter = 0;
{items.map((item) => <li key={++counter}>{item}</li>)}

// ✅ Key derived from the item itself.
{items.map((item) => <li key={item.sku}>{item.name}</li>)}

No natural id? Compose or generate one

// Composite key when a single field isn't unique but a pair is:
<li key={`${category.id}-${item.name}`}>{item.name}</li>

// Or assign an id at creation time and keep it in state:
function addTodo(text) {
    setTodos((prev) => [
        ...prev,
        { id: crypto.randomUUID(), text }, // generated ONCE, then stable
    ]);
}

When Index Keys Are Fine

Index-as-key is not forbidden — it is fine when all three of these hold, because then position is a stable identity:

• The list is static — items are never reordered, inserted, or removed.
• Items have no stable id of their own to use instead.
• List items hold no local state (no inputs, no toggles, no focus to preserve).

// ✅ OK: a fixed set of instructions that never changes order or content.
function Steps() {
    const steps = [
        'Preheat the oven to 200°C',
        'Mix the dry ingredients',
        'Fold in the wet ingredients',
        'Bake for 25 minutes',
    ];

    return (
        <ol>
            {steps.map((step, index) => (
                <li key={index}>{step}</li>
            ))}
        </ol>
    );
}

Fixing Key Warnings

React surfaces two common key problems in the console. Learn to read them.

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

// ❌ Cause: no key at all.
{items.map((item) => <li>{item.name}</li>)}

// ✅ Fix: add a stable key.
{items.map((item) => <li key={item.id}>{item.name}</li>)}

"Encountered two children with the same key"

// ❌ Cause: duplicate ids in the data.
const items = [
    { id: 1, name: 'Apple' },
    { id: 1, name: 'Banana' }, // duplicate!
];

// ✅ Fix: ensure ids are unique, or compose a unique key.
<li key={`${item.id}-${item.name}`}>{item.name}</li>

Duplicate keys are worse than missing ones: React cannot tell the two items apart, so updates can land on the wrong element. A quick way to audit your data in development:

const keys = items.map((item) => item.id);
console.log('Duplicate keys?', keys.length !== new Set(keys).size);

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

Practice & Quiz

function Checklist() {
    const [tasks, setTasks] = useState([
        { text: 'Buy milk',   done: false },
        { text: 'Walk dog',   done: true  },
        { text: 'Write code', done: false },
    ]);

    const remove = (index) =>
        setTasks(tasks.filter((_, i) => i !== index));

    return (
        <ul>
            {tasks.map((task, index) => (
                <li key={index}> {/* ← fix this */}
                    <input type="checkbox" defaultChecked={task.done} />
                    {task.text}
                    <button onClick={() => remove(index)}>✕</button>
                </li>
            ))}
        </ul>
    );
}

function Checklist() {
    const [tasks, setTasks] = useState([
        { id: 't1', text: 'Buy milk',   done: false },
        { id: 't2', text: 'Walk dog',   done: true  },
        { id: 't3', text: 'Write code', done: false },
    ]);

    const remove = (id) =>
        setTasks(tasks.filter((t) => t.id !== id));

    return (
        <ul>
            {tasks.map((task) => (
                <li key={task.id}>
                    <input type="checkbox" defaultChecked={task.done} />
                    {task.text}
                    <button onClick={() => remove(task.id)}>✕</button>
                </li>
            ))}
        </ul>
    );
}

function SeatMap({ seats }) {
    return (
        <ul>
            {seats.map((seat) => (
                <li key={`${seat.row}-${seat.number}`}>
                    Seat {seat.row}{seat.number}
                </li>
            ))}
        </ul>
    );
}

Best Practices & Pitfalls

✅ Do

• Prefer a stable id from your data (database id, SKU, UUID)
• Generate ids once at creation (crypto.randomUUID()) and store them in state
• Compose a key from multiple fields when no single field is unique
• Keep keys unique within each list, not across the whole app

❌ Don't

• Use the array index for dynamic or stateful lists
• Generate keys with Math.random() or Date.now() during render
• Reuse the same id for two items (duplicate-key warning)
• Try to read key as a prop inside the child — it isn't one; pass an explicit id if needed

Summary

📚 Additional Resources

• react.dev — Keeping list items in order with key
• react.dev — Preserving and Resetting State
• react.dev — Resetting state with a key

🚀 What's Next?

Lists decide how many of something to render. The next lesson, Conditional rendering patterns, decides whether to render at all: the && operator (and its zero trap you saw earlier), the ternary, early returns, and element variables — the four tools for showing the right UI for the current state.