Reactで出る『unique key』警告の原因と解決方法

Posted at 2025-09-29

初めに

Reactで開発をしていると、ほぼ確実に目にするのが次の警告です。

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

初めて見ると「動いてはいるけど、なぜ怒られているんだろう？」と戸惑う人も多いと思います。
この警告は、リストレンダリング（.map() など）を行う際に 子要素に一意の key が割り当てられていない 場合に発生します。

このエラーが出る背景と正しい対処方法、さらに実務で遭遇しやすいパターンまで整理して解説していきます。

React はリスト描画時に 兄弟要素の配列を比較し、key を手掛かりに「同じ要素かどうか」を判断する。
そのため .map() が返す最上位の要素に key を付ける必要がある。子要素や孫要素に付けても意味がない。
短縮フラグメント <>...</> には key を指定できないため、必要な場合は <React.Fragment key="...">...</React.Fragment> を使う。

{items.map((item) => {
  return (
    <div>
      <Cell value={item.name} />
    </div>
  );
})}

この場合、.map() が返す最上位要素（ここでは <div>）に key が付与されていないため警告が出ます。

{items.map((item) => (
  <div key={item.id}>
    <Cell value={item.name} />
  </div>
))}

{items.map((item) => (
  <React.Fragment key={item.id}>
    <Cell value={item.name} />
  </React.Fragment>
))}

※短縮記法 <>...</> では key を付けられないため注意。

{items.map((item) => (
  <Row key={item.id} item={item} />
))}

リストの行が複雑になる場合は、専用コンポーネント化した方が可読性・再利用性も高まります。

補足：
{ ... } を使ったアロー関数は return の書き忘れが多発します。
シンプルに書ける 暗黙的 return（=> ( ... )） を使うと安全です。

index を key に使う
並べ替え・挿入・削除が発生するリストでは不適切。要素の state がズレたり、不要な再マウントが頻発する原因になる。
ランダム値やタイムスタンプを key に使う
毎回変わる＝React にとって「毎回別の要素」扱い。入力中の値やフォーカスがリセットされる。
短縮フラグメント <>...</>
key を付けられないため、必要な場合は React.Fragment を明示的に使う。
複数配列を結合して描画する
例：[...A.map(), ...B.map()]
同じ親配列に並ぶため key が衝突しやすい。
→ A:${id} や B:${id} のようにプレフィックスを付けて区別する。
子コンポーネント内部の .map() を見落とす
親で key を付けても、子の配列レンダーに key が無ければ同様に警告が出る。

map / return [ / <> を全文検索
→ 各配列レンダーの 最上位要素に key があるかを確認する。
短縮フラグメントを見直す
<>...</> を使っている場合は React.Fragment に置き換え、必要なら key を付与する。
ヘルパー関数の返り値を確認
関数が直接 JSX を返しているなら、関数コンポーネント化して <Helper ... key={...} /> の形にする。
配列結合を点検
[..., ...] で複数の配列を展開している場合、プレフィックス付きのキー（例：A:${id} / B:${id}）で一意化する。
ESLint を活用
ルール "react/jsx-key": "error" を有効化して、自動的に検出できるようにする。
React DevTools で確認
Components タブから要素を選び、key が付与されているか・値が安定しているかを目視チェックする。

この警告の本質は 「兄弟要素の配列レンダーには、最上位に安定した key が必須」 ということ。
対処に迷ったら：
- 最上位に key を付ける
- Fragment は React.Fragment を使う
- 複雑になったらコンポーネント化する
仕上げに ESLint と React DevTools を組み合わせれば、再発を防ぎつつ安心して開発できる。