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 개발자라면 누구나 한 번쯤은 겪는 매우 흔한 문제입니다. 특히 배열을 렌더링할 때 발생하는 이 경고는 단순히 무시할 수 있는 것처럼 보이지만, 실제로는 애플리케이션의 성능과 안정성에 직접적인 영향을 미칠 수 있습니다. React가 Virtual DOM을 효율적으로 업데이트하기 위해서는 각 리스트 아이템을 고유하게 식별할 수 있어야 하는데, key prop이 바로 이 역할을 담당합니다. 이 글에서는 이 경고가 발생하는 원인부터 실전에서 바로 적용할 수 있는 해결 방법까지 완벽하게 정리해드리겠습니다.

에러 상세 분석

Warning: Each child in a list should have a unique “key” prop은 React가 배열을 렌더링할 때 각 요소에 고유한 key 속성이 없을 때 발생하는 경고입니다. 이 경고는 실제로 애플리케이션을 중단시키지는 않지만, React의 재조정(Reconciliation) 알고리즘이 효율적으로 작동하지 못하게 만듭니다. React는 Virtual DOM을 사용하여 변경사항을 추적하는데, key가 없으면 어떤 아이템이 변경, 추가, 삭제되었는지 정확히 파악할 수 없습니다. 그 결과 불필요한 리렌더링이 발생하여 성능 저하가 일어나고, 특히 입력 필드나 체크박스 같은 상태를 가진 컴포넌트에서는 예상치 못한 동작이 발생할 수 있습니다. 예를 들어, 리스트의 순서가 변경될 때 잘못된 컴포넌트의 상태가 유지되거나 입력값이 엉뚱한 곳에 나타나는 버그가 발생할 수 있습니다. 따라서 이 경고를 해결하는 것은 단순히 콘솔을 깨끗하게 만드는 것 이상의 의미가 있습니다.

발생 원인 5가지

1. key prop 완전히 누락

가장 흔한 원인은 배열을 map() 함수로 렌더링할 때 key prop을 아예 작성하지 않는 경우입니다. React에서 배열의 각 요소를 렌더링할 때는 반드시 최상위 엘리먼트에 key를 추가해야 합니다.

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

많은 개발자들이 배열의 인덱스를 key로 사용하는데, 이는 리스트의 순서가 변경되거나 항목이 추가/삭제될 때 문제를 일으킵니다. 인덱스는 항목 자체를 식별하는 것이 아니라 위치만 나타내기 때문에, 리스트가 재정렬되면 React가 잘못된 컴포넌트를 재사용할 수 있습니다.

3. 중복된 key 값

고유하지 않은 key를 사용하는 경우도 이 경고를 발생시킵니다. 여러 아이템이 같은 key를 가지면 React는 어떤 요소가 변경되었는지 구분할 수 없어 예상치 못한 동작이 발생합니다.

4. Fragment 사용 시 key 누락

React.Fragment를 사용할 때도 key가 필요한 경우가 있습니다. 특히 Fragment를 배열로 렌더링할 때는 단축 문법(<></>) 대신 완전한 Fragment 문법을 사용하고 key를 추가해야 합니다.

5. 중첩된 배열 렌더링

2차원 배열이나 중첩된 리스트를 렌더링할 때 외부 배열에만 key를 추가하고 내부 배열에는 key를 누락하는 경우가 있습니다. 각 레벨의 배열마다 모두 고유한 key가 필요합니다.

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

1. 고유한 ID를 key로 사용 (가장 권장)

데이터에 고유한 ID가 있다면 이것을 key로 사용하는 것이 가장 좋습니다.

const TodoList = ({ todos }) => {
  return (
    

      {todos.map(todo => (
        
{todo.text}
      ))}
    
  );
};

2. 여러 속성 조합으로 고유 key 생성

단일 ID가 없을 때는 여러 속성을 조합하여 고유한 key를 만들 수 있습니다.

const UserList = ({ users }) => {
  return (
    

      {users.map(user => (
        

          {user.name}
        
      ))}
    
  );
};

3. UUID 라이브러리 사용

데이터에 고유 식별자가 없는 경우 UUID 라이브러리로 고유 ID를 생성할 수 있습니다.

import { v4 as uuidv4 } from 'uuid';

const ItemList = ({ items }) => {
  const itemsWithIds = items.map(item => ({
    ...item,
    id: item.id || uuidv4()
  }));

  return (
    

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

4. Fragment에 key 추가

Fragment를 배열로 렌더링할 때는 완전한 문법과 함께 key를 사용합니다.

const TableRows = ({ data }) => {
  return (
    
      {data.map(row => (
        
          
            {row.name}
          
          
            {row.description}
          
        
      ))}
    
  );
};

5. 중첩 배열 처리

중첩된 배열은 각 레벨마다 고유한 key를 할당합니다.

const NestedList = ({ categories }) => {
  return (
    

      {categories.map(category => (
        

          
{category.name}
          

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

6. 인덱스 사용 (최후의 수단)

리스트가 정적이고 재정렬되지 않으며 필터링되지 않는 경우에만 인덱스를 사용할 수 있습니다.

const StaticList = ({ items }) => {
  return (
    

      {items.map((item, index) => (
        
{item}
      ))}
    
  );
};
// 주의: 리스트가 변경될 가능성이 있다면 사용하지 마세요!

7. 컴포넌트에 key 전달

커스텀 컴포넌트를 배열로 렌더링할 때도 key를 전달해야 합니다.

const ProductCard = ({ product }) => (
  

    
{product.name}
    
{product.price}
  
);

const ProductList = ({ products }) => {
  return (
    

      {products.map(product => (
        
      ))}
    
  );
};

예방법과 베스트 프랙티스

데이터 설계 단계에서 고유 ID 포함

백엔드 API를 설계할 때부터 모든 리스트 데이터에 고유 식별자를 포함시키는 것이 좋습니다. 데이터베이스의 Primary Key나 UUID를 활용하면 프론트엔드에서 key 관리가 훨씬 쉬워집니다.

ESLint 규칙 활성화

eslint-plugin-react의 ‘react/jsx-key’ 규칙을 활성화하면 key prop이 누락된 경우 개발 단계에서 즉시 경고를 받을 수 있습니다. .eslintrc 파일에 다음 설정을 추가하세요.

{
  "rules": {
    "react/jsx-key": "error"
  }
}

코드 리뷰 체크리스트 포함

팀 개발 시 코드 리뷰 체크리스트에 “모든 배열 렌더링에 적절한 key가 있는가?”를 포함시켜 Warning: Each child in a list should have a unique “key” prop 문제를 사전에 방지할 수 있습니다.

마무리

Warning: Each child in a list should have a unique “key” prop 경고는 React 개발에서 가장 흔하게 마주치는 문제이지만, 원인과 해결 방법을 정확히 이해하면 쉽게 해결할 수 있습니다. 단순히 경고를 없애는 것이 아니라, React의 효율적인 렌더링 메커니즘을 이해하고 성능 최적화를 실천하는 것이 중요합니다. 가능한 한 고유한 ID를 사용하고, 배열 인덱스는 최후의 수단으로만 사용하며, ESLint 같은 도구를 활용하여 개발 초기 단계에서 문제를 발견하는 습관을 들이세요. 이러한 베스트 프랙티스를 따르면 안정적이고 성능이 우수한 React 애플리케이션을 개발할 수 있을 것입니다.