Keys, Identity, and Reset Patterns

The Key That Unlocks React Behavior

Every confusing React bug you've ever encountered -- state appearing on the wrong list item, inputs losing focus, animations replaying when they shouldn't -- traces back to one thing: how React identifies elements across renders. Keys are the mechanism, and here's the thing: most developers only understand half of it.

// This has a bug. Can you see it?
function ChatList({ chats }) {
  return chats.map((chat, index) => (
    <ChatPreview
      key={index}  // The bug is right here
      chat={chat}
      unreadCount={chat.unread}
    />
  ));
}

When a new message pushes a chat to the top of the list, every ChatPreview after it receives the wrong chat's state. Animations replay. Unread badges show wrong counts. The user sees a different chat's draft message in their input.

The Mental Model

How Keys Work in Reconciliation

During reconciliation, React matches old fibers to new elements. For lists, the matching strategy is:

1. No keys (or all keys are index): Match by position. Element at index 0 maps to old fiber at index 0.
2. With keys: Build a map of key → old fiber. Match new elements by looking up their key in the map.

// Without keys — position-based matching
// Old: [Alice, Bob, Charlie]
// New: [Bob, Charlie]  (Alice removed)

// React's perspective:
// Position 0: Alice → Bob (update Alice's fiber with Bob's props)
// Position 1: Bob → Charlie (update Bob's fiber with Charlie's props)
// Position 2: Charlie → nothing (delete Charlie's fiber)
// Result: 2 updates + 1 deletion = 3 DOM operations
// BUG: Alice's state (draft message, scroll position) now shows on Bob's item

// With keys — identity-based matching
// Old: [Alice(key=1), Bob(key=2), Charlie(key=3)]
// New: [Bob(key=2), Charlie(key=3)]

// React's perspective:
// key=1 (Alice): not in new list → delete
// key=2 (Bob): in both → update props (none changed → skip)
// key=3 (Charlie): in both → update props (none changed → skip)
// Result: 1 deletion. Bob and Charlie keep their state.

The Index-as-Key Bug in Detail

Here's a concrete demonstration of the index-as-key problem:

function TodoList() {
  const [todos, setTodos] = useState([
    { id: 1, text: 'Buy milk' },
    { id: 2, text: 'Walk dog' },
    { id: 3, text: 'Code' },
  ]);

  function removeFirst() {
    setTodos(todos.slice(1)); // Remove "Buy milk"
  }

  return (
    <>
      <button onClick={removeFirst}>Remove First</button>
      {todos.map((todo, index) => (
        <TodoItem key={index} todo={todo} />
      ))}
    </>
  );
}

function TodoItem({ todo }) {
  const [checked, setChecked] = useState(false);
  return (
    <label>
      <input type="checkbox" checked={checked} onChange={() => setChecked(!checked)} />
      {todo.text}
    </label>
  );
}

Scenario: User checks "Buy milk" (index 0). Then clicks "Remove First."

With key={index}:

• Old: [{key:0, "Buy milk" ✓}, {key:1, "Walk dog"}, {key:2, "Code"}]
• New: [{key:0, "Walk dog"}, {key:1, "Code"}]
• React matches key 0 → key 0: updates text from "Buy milk" to "Walk dog" but keeps the checked state
• Result: "Walk dog" appears checked. The user never checked it.

With key={todo.id}:

• Old: [{key:1, "Buy milk" ✓}, {key:2, "Walk dog"}, {key:3, "Code"}]
• New: [{key:2, "Walk dog"}, {key:3, "Code"}]
• React: key 1 deleted, key 2 preserved (unchecked), key 3 preserved (unchecked)
• Result: Correct. "Walk dog" is unchecked.

Key-as-Reset: Intentional Remounting

Here's where keys get really interesting. They aren't just for lists. You can use them on any component to force React to destroy and recreate it:

function UserProfile({ userId }) {
  // When userId changes, the entire form resets
  return <ProfileForm key={userId} userId={userId} />;
}

function ProfileForm({ userId }) {
  const [name, setName] = useState('');
  const [email, setEmail] = useState('');
  // State starts fresh for each userId because the key changed
  // React unmounts the old ProfileForm and mounts a new one

  useEffect(() => {
    fetchUser(userId).then(user => {
      setName(user.name);
      setEmail(user.email);
    });
  }, [userId]);

  return (
    <form>
      <input value={name} onChange={e => setName(e.target.value)} />
      <input value={email} onChange={e => setEmail(e.target.value)} />
    </form>
  );
}

Without key={userId}, switching from user 1 to user 2 would keep the form mounted. The old user's name and email would flash briefly before the effect fetches new data. With the key, React unmounts the old form entirely and mounts a fresh one — no stale data flash.

Production Scenario: The Leaking Chat Input

A chat application has a message input per conversation:

function ChatWindow({ conversationId }) {
  return (
    <div>
      <MessageList conversationId={conversationId} />
      <MessageInput conversationId={conversationId} />
    </div>
  );
}

function MessageInput({ conversationId }) {
  const [draft, setDraft] = useState('');

  return (
    <input
      value={draft}
      onChange={e => setDraft(e.target.value)}
      placeholder="Type a message..."
    />
  );
}

Bug: User types "Hey Alice" in conversation with Alice. Switches to Bob's conversation. The input still shows "Hey Alice." The draft leaked between conversations because MessageInput was never unmounted — React saw the same component type at the same position and reused it.

Fix: Add a key to reset the input per conversation:

function ChatWindow({ conversationId }) {
  return (
    <div>
      <MessageList conversationId={conversationId} />
      <MessageInput key={conversationId} conversationId={conversationId} />
    </div>
  );
}

Now switching conversations unmounts the old MessageInput and mounts a fresh one with empty draft state.

When Index-as-Key is Safe

Before you go adding IDs to everything, let's be fair: index-as-key is not always wrong. It's safe when ALL of these are true:

1. The list is static — items are never reordered, inserted, or deleted
2. Items have no state — no inputs, checkboxes, or component state
3. Items are not animated — no transition state tied to item identity

// Safe: static navigation items, no state, no reordering
const navItems = ['Home', 'About', 'Contact'];
navItems.map((item, i) => <NavLink key={i}>{item}</NavLink>);

// Safe: static table headers
const headers = ['Name', 'Email', 'Role'];
headers.map((h, i) => <th key={i}>{h}</th>);

// NOT safe: any list where items can change
const [todos, setTodos] = useState(initialTodos);
todos.map((todo, i) => <TodoItem key={i} todo={todo} />); // Bug waiting to happen

If in doubt, use a stable unique identifier. The cost of a proper key is negligible, and the bugs from index-as-key are subtle and painful to debug.

Common Mistakes

Challenge

Fix the key bug

Quiz

Key Rules