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을 지정하지 않았을 때 나타납니다. 이 경고는 애플리케이션의 성능 저하와 예상치 못한 렌더링 버그를 유발할 수 있어 반드시 해결해야 합니다. key prop은 React가 Virtual DOM을 효율적으로 업데이트하고 어떤 요소가 변경, 추가, 제거되었는지 식별하는 데 필수적인 역할을 합니다. 이 글에서는 이 경고가 발생하는 원인부터 실전 해결법, 그리고 예방 방법까지 완벽하게 다루겠습니다.

에러 상세 분석

React는 리스트를 렌더링할 때 각 요소를 추적하기 위해 key라는 특별한 속성을 사용합니다. key는 React가 어떤 아이템이 변경되었는지, 추가되었는지, 삭제되었는지 효율적으로 판단하는 힌트를 제공합니다. key가 없으면 React는 모든 요소를 순차적으로 비교해야 하므로 성능이 저하됩니다.

이 경고는 단순한 경고 메시지이지만, 실제로는 심각한 문제를 일으킬 수 있습니다. 예를 들어, 리스트의 순서가 변경되거나 중간에 요소가 삽입될 때 컴포넌트의 state가 잘못된 요소에 연결될 수 있습니다. 또한 입력 필드의 값이 다른 행으로 이동하거나, 체크박스 상태가 뒤섞이는 등의 버그가 발생할 수 있습니다. 따라서 개발 단계에서 이 경고를 무시하지 말고 즉시 해결하는 것이 중요합니다. key는 형제 요소들 사이에서만 고유하면 되며, 전역적으로 고유할 필요는 없습니다.

발생 원인 5가지

1. key prop을 아예 지정하지 않은 경우

가장 기본적인 원인으로, map 함수로 배열을 순회하면서 컴포넌트를 생성할 때 key를 전혀 지정하지 않은 경우입니다. 이는 초보 개발자들이 가장 자주 범하는 실수입니다.

// 잘못된 예시
const items = ['Apple', 'Banana', 'Orange'];
return (
  

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

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

배열의 인덱스를 key로 사용하는 것은 리스트의 순서가 변경되지 않고 항목이 추가/삭제되지 않는 정적인 리스트에서만 안전합니다. 동적 리스트에서 인덱스를 key로 사용하면 성능 문제와 state 버그가 발생할 수 있습니다.

3. key 값이 중복되는 경우

서로 다른 요소에 동일한 key 값을 할당한 경우입니다. 데이터베이스에서 가져온 데이터에 중복된 ID가 있거나, 잘못된 로직으로 key를 생성할 때 발생합니다.

4. Fragment를 사용할 때 key를 누락한 경우

React.Fragment를 사용하여 여러 요소를 그룹화할 때도 key가 필요한데, 단축 문법 <>를 사용하면 key를 전달할 수 없어 문제가 발생합니다.

5. 조건부 렌더링에서 key 관리 실수

조건에 따라 다른 컴포넌트를 렌더링할 때, 각 분기에서 반환되는 요소들에 일관된 key를 적용하지 않으면 경고가 발생할 수 있습니다.

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

1. 고유한 ID를 key로 사용하기

데이터에 이미 고유한 ID가 있다면 이를 key로 사용하는 것이 가장 좋은 방법입니다.

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

return (
  

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

2. 복합 키 생성하기

단일 필드로는 고유성을 보장할 수 없을 때 여러 필드를 조합하여 key를 만듭니다.

const items = [
  { category: 'fruit', name: 'Apple' },
  { category: 'fruit', name: 'Banana' },
  { category: 'vegetable', name: 'Carrot' }
];

return (
  

    {items.map(item => (
      

        {item.category}: {item.name}
      
    ))}
  
);

3. uuid 라이브러리 사용하기

데이터에 고유 ID가 없을 때는 uuid 같은 라이브러리로 고유한 식별자를 생성할 수 있습니다.

import { v4 as uuidv4 } from 'uuid';

const items = ['Apple', 'Banana', 'Orange'].map(item => ({
  id: uuidv4(),
  name: item
}));

return (
  

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

4. Fragment에 key 전달하기

Fragment를 사용할 때는 명시적으로 React.Fragment를 작성하여 key를 전달해야 합니다.

import React from 'react';

const items = [1, 2, 3];

return (
  

    {items.map(item => (
      
        
Term {item}
        
Description {item}
      
    ))}
  
);

5. 안정적인 key 생성 함수 만들기

데이터의 특성을 활용하여 안정적인 key를 생성하는 유틸리티 함수를 만듭니다.

const generateKey = (item, index, prefix = 'item') => {
  // 객체인 경우 주요 속성들을 조합
  if (typeof item === 'object' && item !== null) {
    const keys = Object.keys(item).sort();
    const values = keys.map(k => item[k]).join('-');
    return `${prefix}-${values}`;
  }
  // 원시값인 경우
  return `${prefix}-${item}-${index}`;
};

const items = ['Apple', 'Banana', 'Orange'];

return (
  

    {items.map((item, index) => (
      
{item}
    ))}
  
);

6. 중첩된 리스트 처리하기

중첩된 배열을 렌더링할 때는 각 레벨에서 고유한 key를 지정해야 합니다.

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

return (
  

    {categories.map(category => (
      

        
{category.name}
        

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

7. 컴포넌트 분리로 key 관리 개선하기

복잡한 리스트 아이템은 별도의 컴포넌트로 분리하여 key 관리를 명확하게 만듭니다.

const ListItem = ({ item }) => (
  

    
{item.title}
    
{item.description}
  
);

const ItemList = ({ items }) => (
  

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

예방법과 베스트 프랙티스

“Warning: Each child in a list should have a unique “key” prop” 경고를 예방하려면 다음 원칙을 따르세요. 첫째, 데이터 모델을 설계할 때부터 각 항목에 고유 식별자를 포함시키세요. 데이터베이스의 primary key나 UUID를 활용하는 것이 좋습니다. 둘째, 배열 인덱스를 key로 사용하는 것은 최후의 수단으로만 고려하고, 정적이고 순서가 변하지 않는 리스트에만 사용하세요.

셋째, ESLint의 react/jsx-key 규칙을 활성화하여 key 누락을 자동으로 감지하세요. 넷째, 코드 리뷰 시 리스트 렌더링 부분을 특별히 점검하는 체크리스트를 만드세요. 다섯째, key는 형제 요소 간에만 고유하면 되므로, 전체 애플리케이션에서 고유할 필요는 없습니다. 마지막으로, key는 변경되지 않고 안정적이어야 하며, 렌더링마다 새로 생성되어서는 안 됩니다. Math.random()이나 Date.now()를 key로 사용하지 마세요.

마무리

React에서 Warning: Each child in a list should have a unique “key” prop 경고는 흔하지만 결코 무시해서는 안 되는 중요한 메시지입니다. key prop은 React의 재조정(Reconciliation) 알고리즘이 효율적으로 작동하도록 돕고, 예상치 못한 버그를 방지합니다. 이 글에서 소개한 원인 분석과 7가지 해결 방법을 활용하면 이 경고를 완벽하게 해결할 수 있습니다. 고유한 ID를 key로 사용하는 것을 최우선으로 하고, 불가피한 경우에만 인덱스를 사용하세요. 올바른 key 사용은 React 애플리케이션의 성능과 안정성을 크게 향상시킵니다. 지금 바로 프로젝트의 리스트 렌더링 코드를 점검하고 개선해보세요!