Lists and Keys

Most screens are lists. An employee directory, a course catalogue, the lessons in a module. In React you render one by turning an array of data into an array of elements, which is what Array.map already does.

React then asks for one extra thing: a key on each item. It looks like a formality, and it is the source of one of the most confusing bugs a React developer meets, because the symptom appears nowhere near the cause.

interface Employee {
  id: string;
  name: string;
  department: string;
  jobTitle: string;
}

export function EmployeeTable({ employees }: { employees: Employee[] }) {
  if (employees.length === 0) {
    return <p className="text-sm text-slate-600">No employees match these filters.</p>;
  }

  return (
    <table className="w-full text-left">
      <caption className="sr-only">Employees matching the current filters</caption>
      <thead>
        <tr>
          <th scope="col">Name</th>
          <th scope="col">Department</th>
          <th scope="col">Job title</th>
        </tr>
      </thead>
      <tbody>
        {employees.map((employee) => (
          <tr key={employee.id}>
            <td>{employee.name}</td>
            <td>{employee.department}</td>
            <td>{employee.jobTitle}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

• map returns an array of row elements, and React renders an array by rendering each item in order. There is no loop syntax because none is needed.
• The key goes on the outermost element produced by the callback — the tr, not the td inside it.
• employee.id comes from the data and identifies that person regardless of where they appear in the array. That is exactly what a key is supposed to be.
• The empty case is handled before the table. An empty result is a normal outcome of filtering, so it gets a sentence rather than an empty table with headings and nothing under them.
• scope="col" on the header cells and a caption give screen reader users the same structure sighted users get from the visual layout. The caption is visually hidden here because the heading above the table already says it.

When data changes, React renders the list again and compares the new elements with the previous ones. It has to decide, for each element, whether this is the same item as before — in which case the existing DOM node and any state inside it are reused — or a different item that needs a fresh node.

The key is how React answers that question. Same key means same item. Different key means a different item, so tear the old one down and build a new one.

This matters because a row is often more than text. It may hold a checkbox, an expanded panel, an uncontrolled input, scroll position, or focus. None of that lives in your data. It lives in the DOM and in the component's own state, attached to whichever element React believes is that row.

import { useState } from "react";

function EmployeeNoteRow({ employee }: { employee: Employee }) {
  // State that belongs to this row and is not in the employee data.
  const [note, setNote] = useState("");

  return (
    <li className="py-2">
      <p className="font-medium">{employee.name}</p>
      <label className="text-sm">
        Note
        <input value={note} onChange={(event) => setNote(event.target.value)} />
      </label>
    </li>
  );
}

export function EmployeeNotes({ employees }: { employees: Employee[] }) {
  return (
    <ul>
      {employees.map((employee, index) => (
        // Wrong. The index describes a position, not a person.
        <EmployeeNoteRow key={index} employee={employee} />
      ))}
    </ul>
  );
}

• Each row owns a note that exists only in the component, not in the employees array. This is ordinary — selection, expansion and draft text all work this way.
• The key is the array index, so the first row is key 0 for as long as the list has a first row, whoever that happens to be.
• Nothing looks wrong on first render. Names line up with notes, and the code reviews cleanly. The failure needs the list to change.