React Key Prop Explained

The key prop is crucial for React's reconciliation algorithm. Here's how to use it correctly.

Why Keys Matter#

// Without keys - React can't track items efficiently
function BadList({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <li>{item.name}</li> // Warning: Each child should have a unique "key" prop
      ))}
    </ul>
  );
}

// With keys - React tracks each item
function GoodList({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );
}

// What happens without keys:
// 1. React can't identify which items changed
// 2. May recreate DOM elements unnecessarily
// 3. Can cause bugs with component state
// 4. Input values may shift to wrong items

Choosing Keys#

// BEST: Unique, stable IDs from data
function UserList({ users }) {
  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

// GOOD: Combination of fields for uniqueness
function CommentList({ comments }) {
  return (
    <ul>
      {comments.map((comment) => (
        <li key={`${comment.postId}-${comment.id}`}>
          {comment.text}
        </li>
      ))}
    </ul>
  );
}

// OK: Index as last resort (static lists only)
function StaticNavigation() {
  const links = ['Home', 'About', 'Contact'];

  return (
    <nav>
      {links.map((link, index) => (
        <a key={index} href={`/${link.toLowerCase()}`}>
          {link}
        </a>
      ))}
    </nav>
  );
}

// BAD: Random values - defeats the purpose
function BadRandomKeys({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <li key={Math.random()}>{item.name}</li> // Never do this!
      ))}
    </ul>
  );
}

Index Keys Pitfalls#

// Problem: Index keys with reorderable lists
function TodoList({ todos, onToggle, onDelete }) {
  return (
    <ul>
      {todos.map((todo, index) => (
        <TodoItem
          key={index} // Bug: state gets mixed up on reorder
          todo={todo}
          onToggle={() => onToggle(todo.id)}
          onDelete={() => onDelete(todo.id)}
        />
      ))}
    </ul>
  );
}

// Problem: Index keys with inputs
function EditableList({ items }) {
  return (
    <ul>
      {items.map((item, index) => (
        <li key={index}>
          <input defaultValue={item.text} />
          {/* Deleting an item causes input values to shift! */}
        </li>
      ))}
    </ul>
  );
}

// Solution: Use stable IDs
function FixedEditableList({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>
          <input defaultValue={item.text} />
        </li>
      ))}
    </ul>
  );
}

Generating Keys#

// Generate IDs when creating items
let nextId = 0;

function createItem(text) {
  return {
    id: nextId++,
    text,
  };
}

// UUID for more robust IDs
import { v4 as uuid } from 'uuid';

function createItem(text) {
  return {
    id: uuid(),
    text,
  };
}

// Crypto for unique IDs
function generateId() {
  return crypto.randomUUID();
}

// Using useId for component-scoped IDs (React 18+)
import { useId } from 'react';

function FormField({ label }) {
  const id = useId();
  return (
    <>
      <label htmlFor={id}>{label}</label>
      <input id={id} />
    </>
  );
}

Keys with Fragments#

// Keys on Fragment shorthand (doesn't work)
function Columns({ data }) {
  return (
    <>
      {data.map((item) => (
        // Can't add key to <>...</>
        <>
          <td>{item.name}</td>
          <td>{item.value}</td>
        </>
      ))}
    </>
  );
}

// Use React.Fragment with key
function ColumnsFixed({ data }) {
  return (
    <>
      {data.map((item) => (
        <React.Fragment key={item.id}>
          <td>{item.name}</td>
          <td>{item.value}</td>
        </React.Fragment>
      ))}
    </>
  );
}

Keys for Component Reset#

// Force component remount with key change
function ProfilePage({ userId }) {
  return (
    <div>
      <h1>Profile</h1>
      {/* ProfileContent resets when userId changes */}
      <ProfileContent key={userId} userId={userId} />
    </div>
  );
}

function ProfileContent({ userId }) {
  const [isEditing, setIsEditing] = useState(false);
  const [draft, setDraft] = useState('');

  // State resets when key changes
  return (
    <div>
      <p>User: {userId}</p>
      {isEditing && <input value={draft} onChange={e => setDraft(e.target.value)} />}
    </div>
  );
}

// Resetting form on submission
function Form({ onSubmit }) {
  const [key, setKey] = useState(0);

  const handleSubmit = (data) => {
    onSubmit(data);
    setKey(k => k + 1); // Reset form
  };

  return (
    <FormContent
      key={key}
      onSubmit={handleSubmit}
    />
  );
}

Reconciliation Deep Dive#

// How React uses keys for reconciliation

// Initial render
<ul>
  <li key="a">Alice</li>
  <li key="b">Bob</li>
  <li key="c">Carol</li>
</ul>

// After reorder: React matches by key
<ul>
  <li key="c">Carol</li>  // Moved from position 2
  <li key="a">Alice</li>  // Moved from position 0
  <li key="b">Bob</li>    // Stayed at same key, different position
</ul>

// With index keys - React sees different content at each position
// Initial: [0: Alice, 1: Bob, 2: Carol]
// After:   [0: Carol, 1: Alice, 2: Bob]
// React thinks position 0 changed from Alice to Carol!

// Nested lists with compound keys
function NestedList({ categories }) {
  return (
    <div>
      {categories.map((category) => (
        <section key={category.id}>
          <h2>{category.name}</h2>
          <ul>
            {category.items.map((item) => (
              <li key={item.id}>{item.name}</li>
            ))}
          </ul>
        </section>
      ))}
    </div>
  );
}

Performance Implications#

// Keys help React optimize updates
function OptimizedList({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <ExpensiveItem key={item.id} item={item} />
      ))}
    </ul>
  );
}

const ExpensiveItem = React.memo(({ item }) => {
  // Heavy computation
  return <li>{computeExpensively(item)}</li>;
});

// Without stable keys, memo is useless
// React can't tell which component to reuse

// Measuring performance
function MeasuredList({ items }) {
  console.time('render');

  const result = (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );

  console.timeEnd('render');
  return result;
}

Common Mistakes#

// Mistake 1: Keys in wrong place
function WrongKeyPlacement({ items }) {
  return (
    <ul>
      {items.map((item) => (
        // Key should be on the outermost element in the map
        <li>
          <span key={item.id}>{item.name}</span> {/* Wrong! */}
        </li>
      ))}
    </ul>
  );
}

// Correct
function CorrectKeyPlacement({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>
          <span>{item.name}</span>
        </li>
      ))}
    </ul>
  );
}

// Mistake 2: Keys not unique within list
function NonUniqueKeys({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.category}> {/* Multiple items may share category */}
          {item.name}
        </li>
      ))}
    </ul>
  );
}

// Mistake 3: Changing keys unnecessarily
function UnstableKeys({ items }) {
  return (
    <ul>
      {items.map((item, index) => (
        <li key={`${item.id}-${Date.now()}`}> {/* Changes every render! */}
          {item.name}
        </li>
      ))}
    </ul>
  );
}

Best Practices#

Key Selection:
✓ Use unique IDs from data
✓ Generate IDs when items are created
✓ Use stable, predictable values
✓ Keep keys unique among siblings

When Index is OK:
✓ Static, never-reordered lists
✓ Items have no state
✓ Items are never filtered/sorted
✓ List is not editable

Performance:
✓ Combine with React.memo
✓ Use stable object references
✓ Avoid computing keys expensively
✓ Profile with React DevTools

Avoid:
✗ Random values as keys
✗ Index keys for dynamic lists
✗ Changing keys unnecessarily
✗ Duplicate keys in same list

Keys are essential for React's efficient list rendering. Use stable, unique IDs from your data, avoid index keys for dynamic lists, and leverage keys to force component remounts when needed. Proper key usage improves performance and prevents subtle bugs.