Blog

Warning: Each child in a list should have a unique “key” prop 에러란?

React 개발을 하다 보면 콘솔 창에서 “Warning: Each child in a list should have a unique “key” prop”라는 경고 메시지를 자주 마주치게 됩니다. 이 경고는 React가 리스트 형태로 렌더링되는 요소들을 효율적으로 관리하기 위해 필요한 key prop이 누락되었거나 부적절하게 사용되었을 때 발생합니다. 비록 애플리케이션이 정상적으로 작동하는 것처럼 보일 수 있지만, 이 경고를 무시하면 성능 저하, 예상치 못한 렌더링 버그, 상태 관리 문제 등이 발생할 수 있습니다. 따라서 이 경고의 원인을 정확히 이해하고 올바르게 해결하는 것이 중요합니다.

에러 상세 분석

React는 Virtual DOM을 사용하여 UI를 효율적으로 업데이트합니다. 리스트가 렌더링될 때 React는 각 요소를 추적하고 변경 사항을 감지하여 필요한 부분만 실제 DOM에 반영합니다. 이때 key prop은 각 요소의 고유 식별자 역할을 합니다.

key가 없으면 React는 리스트의 어떤 항목이 변경, 추가 또는 삭제되었는지 정확히 파악할 수 없습니다. 예를 들어 리스트의 첫 번째 항목이 삭제되면 React는 key가 없는 경우 모든 항목을 순서대로 비교하며 불필요한 재렌더링을 수행하게 됩니다. 이는 성능 저하로 이어지며, 특히 입력 필드나 애니메이션이 포함된 복잡한 컴포넌트에서는 상태가 잘못된 요소에 할당되는 버그가 발생할 수 있습니다.

이러한 이유로 React는 개발 모드에서 key prop이 누락된 경우 “Warning: Each child in a list should have a unique “key” prop” 경고를 표시하여 개발자에게 문제를 알립니다.

발생 원인 5가지

1. key prop 완전 누락

가장 흔한 원인은 배열을 map() 함수로 렌더링할 때 key를 아예 제공하지 않는 경우입니다. React는 각 반복 요소를 구별할 수 없어 경고를 발생시킵니다.

// 잘못된 예시
const users = ['Alice', 'Bob', 'Charlie'];
return (
  

    {users.map(user => 
{user}
)}
  
);

2. 배열 인덱스를 key로 사용

배열의 index를 key로 사용하는 것은 일시적인 해결책처럼 보이지만, 리스트의 순서가 변경되거나 항목이 추가/삭제될 때 심각한 문제를 야기합니다. 인덱스는 항목 자체의 고유성을 나타내지 않기 때문입니다.

3. 중복된 key 값 사용

여러 요소에 동일한 key 값을 사용하면 React가 요소를 구별할 수 없게 됩니다. 이는 데이터베이스에서 가져온 ID가 중복되거나 임의로 생성한 key가 충돌할 때 발생합니다.

4. 중첩된 리스트에서 key 누락

외부 리스트에는 key를 제공했지만 내부의 중첩된 리스트에는 key를 제공하지 않은 경우입니다. 모든 레벨의 리스트에 key가 필요합니다.

5. Fragment 사용 시 key 미제공

React.Fragment를 사용하여 여러 요소를 반환할 때, Fragment 자체에도 key가 필요한 경우가 있습니다. 특히 map() 함수 내에서 Fragment를 사용할 때 주의해야 합니다.

해결방법 7가지 (코드 포함)

방법 1: 고유한 ID를 key로 사용

데이터베이스에서 가져온 고유 ID나 UUID를 key로 사용하는 것이 가장 안전하고 권장되는 방법입니다.

const users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
  { id: 3, name: 'Charlie' }
];

return (
  

    {users.map(user => (
      
{user.name}
    ))}
  
);

방법 2: 복합 key 생성

단일 속성으로 고유성을 보장할 수 없을 때는 여러 속성을 조합하여 고유한 key를 만들 수 있습니다.

const orders = [
  { userId: 1, productId: 101, date: '2025-01-01' },
  { userId: 1, productId: 102, date: '2025-01-02' }
];

return (
  

    {orders.map(order => (
      

        User {order.userId} ordered Product {order.productId}
      
    ))}
  
);

방법 3: 안정적인 고유 식별자 라이브러리 사용

데이터에 고유 ID가 없는 경우 uuid 같은 라이브러리를 사용하여 안정적인 식별자를 생성할 수 있습니다.

import { v4 as uuidv4 } from 'uuid';

// 데이터 생성 시 ID 할당
const items = ['Apple', 'Banana', 'Orange'].map(item => ({
  id: uuidv4(),
  name: item
}));

return (
  

    {items.map(item => (
      
{item.name}
    ))}
  
);

방법 4: 정적 리스트의 경우 인덱스 허용 (제한적)

리스트가 절대 변경되지 않고 재정렬되지 않는 정적인 경우에만 인덱스를 사용할 수 있습니다.

const staticMenu = ['Home', 'About', 'Contact'];

return (
  
);

방법 5: Fragment에 key 제공

여러 요소를 그룹화할 때 Fragment에도 key를 제공해야 합니다.

import React from 'react';

const glossary = [
  { id: 1, term: 'React', definition: 'A JavaScript library' },
  { id: 2, term: 'Component', definition: 'A reusable piece of UI' }
];

return (
  

    {glossary.map(item => (
      
        
{item.term}
        
{item.definition}
      
    ))}
  
);

방법 6: 중첩 리스트 처리

중첩된 리스트의 경우 각 레벨마다 고유한 key를 제공해야 합니다.

const categories = [
  { id: 1, name: 'Fruits', items: [
    { id: 101, name: 'Apple' },
    { id: 102, name: 'Banana' }
  ]},
  { id: 2, name: 'Vegetables', items: [
    { id: 201, name: 'Carrot' },
    { id: 202, name: 'Broccoli' }
  ]}
];

return (
  

    {categories.map(category => (
      

        
{category.name}
        

          {category.items.map(item => (
            
{item.name}
          ))}
        
      
    ))}
  
);

방법 7: 컴포넌트 추출 시 key 위치 주의

컴포넌트를 추출할 때 key는 map() 함수가 있는 곳의 요소에 제공해야 합니다.

// ListItem 컴포넌트
function ListItem({ name }) {
  return 
{name}
;
}

// 올바른 사용
function UserList({ users }) {
  return (
    

      {users.map(user => (
        
      ))}
    
  );
}

예방법과 베스트 프랙티스

1. 데이터 설계 단계부터 고유 ID 포함

API 설계나 상태 관리 시 모든 리스트 아이템에 고유 ID를 포함시키는 것이 좋습니다. 백엔드에서 데이터를 받아올 때 이미 ID가 있다면 key 문제를 미연에 방지할 수 있습니다.

2. ESLint 규칙 활용

eslint-plugin-react의 ‘react/jsx-key’ 규칙을 활성화하면 key가 누락된 경우 개발 단계에서 즉시 경고를 받을 수 있습니다.

3. key 값의 안정성 보장

key 값은 렌더링 간에 안정적이어야 합니다. Math.random()이나 Date.now()처럼 매번 변경되는 값을 key로 사용하지 마세요. 이는 불필요한 재렌더링을 유발하고 컴포넌트 상태를 초기화시킬 수 있습니다.

4. 형제 요소 간 고유성만 보장

key는 전역적으로 고유할 필요는 없으며, 같은 부모를 가진 형제 요소들 사이에서만 고유하면 됩니다. 다른 리스트에서 같은 key를 사용해도 문제없습니다.

마무리

“Warning: Each child in a list should have a unique “key” prop” 경고는 React 개발에서 흔히 마주치는 문제이지만, 올바른 이해와 접근으로 쉽게 해결할 수 있습니다. 고유하고 안정적인 ID를 key로 사용하고, 인덱스 사용은 정적 리스트에만 제한하며, 중첩 리스트와 Fragment의 경우에도 적절히 key를 제공하는 것이 중요합니다. 이러한 베스트 프랙티스를 따르면 성능이 최적화되고 버그 없는 안정적인 React 애플리케이션을 개발할 수 있습니다. 앞으로 리스트를 렌더링할 때는 항상 적절한 key prop을 제공하는 습관을 들이시기 바랍니다.