Reactのmapで出るkeyの警告の原因と直し方

​​React​TypeScript,Vite,トラブルシュート

React で配列を map して一覧を描くと、ブラウザーのコンソールに Each child in a list should have a unique "key" prop. と出ることがあります。原因は、map が返す要素に key を付けていないことです。<li key={item.id}> のように、データの id を key に渡すと警告は消えます。

私は検証環境でこの警告をわざと出し、コンソールに出た文と、直したあとに消えることを確かめました。key を付けたつもりでも警告が消えない2つの書き方(子コンポーネントの中の要素に key を書いた場合と、<>...</> で囲んだ場合)と、key の値が重なったときに出る別の警告もあわせて試しています。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。npm create vite@latest の react-ts テンプレートで作ったプロジェクト(react / react-dom 19.3.1、Vite 8.3.8、TypeScript 7.0.2、oxlint 1.93.0)で、コンポーネントを StrictMode で囲んで試しました。ページは Chromium 153 を Playwright 1.63.0 で操作して開き、DevTools の画面は、画面ありの Chromium を仮想ディスプレイ(Xvfb)で動かして撮りました。Next.js などのフレームワークや、Chromium 以外のブラウザーでの表示は試していません。

コンソールに出たメッセージ

次のコンポーネントを開発サーバー(npm run dev と同じ vite)で開きました。items は、id・name・color を持つ3件の配列です。

ts
export type Item = { id: string; name: string; color: string };

export const items: Item[] = [
  { id: 'apple', name: 'りんご', color: '赤' },
  { id: 'banana', name: 'バナナ', color: '黄' },
  { id: 'cherry', name: 'さくらんぼ', color: '赤' },
];
tsx
import { items } from './items';

// まちがい:map で返す <li> に key がない
export default function BadNoKey() {
  return (
    <ul>
      {items.map((item) => (
        <li>{item.name}</li>
      ))}
    </ul>
  );
}

一覧はふつうに表示されました。コンソールには、React DevTools の案内のほかに、次のメッセージが1件だけ出ました。

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

Check the render method of `BadNoKey`. See https://react.dev/link/warning-keys for more information.

この記事では警告と呼んでいますが、React はこれを console.error で出しています。そのため DevTools のコンソールでは、黄色ではなく赤い行で表示されます。2行目の Check the render method of のあとには、この例では map を書いた BadNoKey の名前が入りました。直す場所は、このコンポーネントの中の map です。

DevTools のコンソールに、赤い行で「Each child in a list should have a unique "key" prop.」と「Check the render method of `BadNoKey`.」が出ている。上のページには、りんご・バナナ・さくらんぼの一覧が表示されている
key のない一覧を開いたところ。一覧は表示され、コンソールに赤い行が1件出た

メッセージの最後の URL(https://react.dev/link/warning-keys)は、react.dev の設定では、開くと公式ドキュメントの一覧のレンダーの節にある、key の説明に移ります。

データの id を key に渡すと、警告が消える

map が返す <li> に、データの id を key として渡します。

tsx
import { items } from './items';

// 直したもの:データの id を key に渡す
export default function GoodKey() {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );
}

直したページを同じ開発サーバーで開くと、コンソールに出たのは React DevTools の案内だけでした。一覧の表示は、直す前と変わりません。

直したページ。上には同じ一覧が表示され、下の DevTools のコンソールには React DevTools の案内の1行だけが出ている
key を付けたページを開いたところ。赤い行は出ていない

key には、兄弟の中で重ならない文字列か数値を渡します。公式ドキュメントでは、データベースから来たデータならその id を、ブラウザーの中で作るデータなら、作るときに連番や crypto.randomUUID() で id を付けておくよう勧めています(key をどこから持ってくるかの節)。

子コンポーネントの中に key を書いても消えない

一覧の1行をコンポーネントに分けたとき、key をそのコンポーネントの中の <li> に書いてしまうと、警告は消えません。

tsx
import type { Item } from './items';

export default function ItemRow({ item }: { item: Item }) {
  return <li key={item.id}>{item.name}</li>;
}
tsx
import { items } from './items';
import ItemRow from './ItemRow';

// まちがい:key を ItemRow の中の <li> に書いていて、map が返す <ItemRow> には付けていない
export default function BadKeyInChild() {
  return (
    <ul>
      {items.map((item) => (
        <ItemRow item={item} />
      ))}
    </ul>
  );
}

このページを開くと、さきほどと同じ文のメッセージが出ました。Check the render method of のあとの名前は BadKeyInChild で、map を書いた親のほうでした。

key が必要なのは、map が返す要素そのものです。ここでは <ItemRow> が並ぶので、<ItemRow> に key を付けます。

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

こう直すと、警告は出なくなりました。公式ドキュメントにある、一覧の1件をコンポーネントに分けるチャレンジの解答でも、Recipe が返す <div> ではなく、<Recipe> のほうに key を書いています。なお、key は props としてコンポーネントに渡りません。子のコンポーネントで id を使いたいときは、key とは別の props で渡します(key の注意点)。

Fragment の短い書き方(<>...</>)では key を渡せない

1件ごとに <dt> と <dd> のような複数の要素を返したいとき、<>...</> で囲むと、同じ警告が出ました(コンポーネント名は BadFragment)。

tsx
import { items } from './items';

// まちがい:<>...</> には key を書けない
export default function BadFragment() {
  return (
    <dl>
      {items.map((item) => (
        <>
          <dt>{item.name}</dt>
          <dd>{item.color}</dd>
        </>
      ))}
    </dl>
  );
}

<>...</> の書き方には key を書けません。Fragment のリファレンスにあるとおり、react から Fragment を読み込み、<Fragment key={...}> と書きます。

tsx
import { Fragment } from 'react';
import { items } from './items';

// 直したもの:Fragment と書いて key を渡す
export default function GoodFragment() {
  return (
    <dl>
      {items.map((item) => (
        <Fragment key={item.id}>
          <dt>{item.name}</dt>
          <dd>{item.color}</dd>
        </Fragment>
      ))}
    </dl>
  );
}

この形に直すと、警告は出なくなりました。描かれる HTML は、直す前と同じ <dt> と <dd> の並びです。

key の値が重なると、別のメッセージが出る

key を付けても、値が兄弟の中で重なると別のメッセージになります。次の例では、色を key にしたため、りんごとさくらんぼがどちらも 赤 になります。

tsx
import { items } from './items';

// まちがい:色は重なることがあるので、key に使うと同じ値が2つできる
export default function DuplicateKey() {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.color}>{item.name}</li>
      ))}
    </ul>
  );
}

コンソールには、こちらも赤い行で次の文が出ました。

text
Encountered two children with the same key, `赤`. Keys should be unique so that components maintain their identity across updates. Non-unique keys may cause children to be duplicated and/or omitted — the behavior is unsupported and could change in a future version.

重なった値(赤)が文の中に入るので、どの値が重なったかが分かります。公式ドキュメントの key の決まりのとおり、key は兄弟の中で重ならない値にします。このデータなら item.id を使えば直ります。

index を key にすると警告は消えるが、並べ替えには向かない

map の2つ目の引数の index を key={index} と渡しても、警告は出なくなりました。ただし、公式ドキュメントの key についての注意では、key を書かなかったときに React が使うのも index だと説明しています。そのうえで、項目を途中に足したり、消したり、並べ替えたりする一覧では、index を key にすると分かりにくい不具合のもとになると注意しています。key={Math.random()} のように、レンダーのたびに値を作るのもよくない、とされています。

index で済むのは、項目の追加・削除・並べ替えがない一覧に限られます。公式のチャレンジにある、行が並べ替わらない詩の例では、index を key にしてよいとしています。項目が動く一覧では、データに id を持たせて、それを key に渡します。

型チェックでは見つからず、lint で一部が見つかる

key の付け忘れは、TypeScript の型チェックではエラーになりません。検証用のプロジェクトで npx tsc -p tsconfig.app.json --noEmit を実行すると、エラーは0件でした。

テンプレートに入っている lint ツールの oxlint は、設定を変えずに npx oxlint src を実行したところ、次の2か所に警告を出しました。

text
src/BadNoKey.tsx:7:14: warning react(jsx-key): Missing "key" prop for element in iterator. help: Add a "key" prop to the element in the iterator (https://react.dev/learn/rendering-lists#keeping-list-items-in-order-with-key).
src/BadKeyInChild.tsx:8:14: warning react(jsx-key): Missing "key" prop for element in iterator. help: Add a "key" prop to the element in the iterator (https://react.dev/learn/rendering-lists#keeping-list-items-in-order-with-key).

一方、<>...</> で囲んだ BadFragment.tsx と、値が重なる DuplicateKey.tsx には、何も出ませんでした。この2つは、開発サーバーでページを開いたときのコンソールで気づくことになります。

本番用のビルドでは、何も出ない

npm run build でビルドし、npx vite preview で開くと、key のない一覧(BadNoKey)、<>...</> の一覧(BadFragment)、key が重なる一覧(DuplicateKey)のどれを開いても、コンソールには何も出ませんでした。react-dom 19.3.1 のファイルを調べると、key がないときの文(Each child in a list should have a unique "key" prop.)は、開発用の react-dom-client.development.js には入っていて、本番用の react-dom-client.production.js には入っていません。

本番用のビルドで何も出ないからといって、直ったわけではありません。この警告は、開発サーバーで一覧のページを開いたときのコンソールで確かめます。

​Posted by 86