🛠️ 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 개발을 하다 보면 콘솔창에서 “Warning: Each child in a list should have a unique “key” prop” 에러 메시지를 자주 마주치게 됩니다. 이 경고는 React에서 배열을 렌더링할 때 각 요소에 고유한 key prop을 제공하지 않았을 때 발생합니다. 많은 개발자들이 초기에 경험하는 이 에러는 단순해 보이지만, React의 핵심 개념인 가상 DOM과 깊은 관련이 있습니다. 이 글에서는 이 경고가 왜 발생하는지, 어떻게 해결하는지, 그리고 어떻게 예방할 수 있는지 상세하게 알아보겠습니다.

에러 상세 분석

이 경고 메시지는 React의 재조정(Reconciliation) 알고리즘과 직접적으로 연관되어 있습니다. React는 가상 DOM을 사용하여 효율적으로 UI를 업데이트하는데, 리스트의 각 항목을 구별하기 위해 key prop이 필요합니다. key가 없으면 React는 어떤 항목이 변경되었는지, 추가되었는지, 삭제되었는지 정확하게 파악할 수 없습니다.

key prop은 React가 컴포넌트의 identity를 추적하는 데 사용됩니다. 올바른 key를 제공하면 React는 DOM 조작을 최소화하고 성능을 최적화할 수 있습니다. 반대로 key가 없거나 잘못된 key를 사용하면 불필요한 리렌더링이 발생하고, 심각한 경우 컴포넌트 상태가 잘못 유지되어 버그가 발생할 수 있습니다. 특히 입력 필드나 애니메이션이 포함된 리스트에서는 더욱 문제가 될 수 있습니다.

발생 원인 5가지

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

가장 흔한 원인으로, map() 함수로 배열을 렌더링할 때 key를 전혀 제공하지 않는 경우입니다. 초보 개발자들이 가장 많이 범하는 실수입니다.

// 잘못된 예시
const items = ['사과', '바나나', '오렌지'];
return (
  

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

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

배열의 인덱스를 key로 사용하는 것은 임시방편일 뿐 권장되지 않습니다. 항목이 추가되거나 삭제되면 인덱스가 변경되어 예상치 못한 동작이 발생할 수 있습니다.

// 비권장 예시
{items.map((item, index) => 
{item}
)}

3. 중복된 key 값을 사용한 경우

데이터에 중복된 값이 있어 같은 key가 여러 요소에 할당되는 경우입니다. 이는 React가 각 요소를 구별할 수 없게 만듭니다.

4. Fragment에 key를 누락한 경우

여러 요소를 반환할 때 Fragment를 사용하면서 key를 제공하지 않은 경우입니다. Fragment에도 key가 필요할 때가 있습니다.

5. 동적으로 생성된 컴포넌트에 key 누락

조건부 렌더링이나 동적 컴포넌트 생성 시 key를 빠뜨리는 경우가 많습니다. 특히 복잡한 컴포넌트 구조에서 자주 발생합니다.

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

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

데이터베이스에서 가져온 고유 ID를 key로 사용하는 것이 가장 이상적입니다.

const users = [
  { id: 1, name: '김철수' },
  { id: 2, name: '이영희' },
  { id: 3, name: '박민수' }
];

return (
  

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

2. UUID 라이브러리 사용하기

고유 ID가 없는 경우 UUID를 생성하여 사용할 수 있습니다.

import { v4 as uuidv4 } from 'uuid';

const items = ['사과', '바나나', '오렌지'].map(item => ({
  id: uuidv4(),
  name: item
}));

return (
  

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

3. 여러 속성을 조합한 고유 key 생성

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

const products = [
  { category: '과일', name: '사과', price: 1000 },
  { category: '채소', name: '당근', price: 500 }
];

return (
  

    {products.map(product => (
      

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

4. Fragment에 key 추가하기

Fragment를 사용할 때도 key를 추가해야 하는 경우가 있습니다.

import React, { Fragment } from 'react';

const items = [
  { id: 1, title: '제목1', desc: '설명1' },
  { id: 2, title: '제목2', desc: '설명2' }
];

return (
  

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

5. 중첩된 리스트에서 각각 key 제공

중첩된 리스트는 각 레벨마다 고유한 key가 필요합니다.

const categories = [
  { id: 1, name: '과일', items: ['사과', '바나나'] },
  { id: 2, name: '채소', items: ['당근', '양배추'] }
];

return (
  

    {categories.map(category => (
      

        
{category.name}
        

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

6. 컴포넌트를 분리하여 key 관리

복잡한 리스트는 별도 컴포넌트로 분리하면 key 관리가 쉬워집니다.

const ListItem = ({ item }) => (
  

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

const List = ({ items }) => (
  

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

7. 정적 리스트에서만 인덱스 사용 (최후의 수단)

절대 변경되지 않는 정적 리스트에서만 인덱스를 key로 사용할 수 있습니다.

// 정적이고 순서가 절대 바뀌지 않는 경우에만
const STATIC_MENU = ['홈', '소개', '연락처'];

return (
  
);

예방법과 베스트 프랙티스

1. 데이터 설계 단계에서 고유 ID 포함: 백엔드에서 데이터를 설계할 때 항상 고유 ID를 포함시키세요. 이는 프론트엔드 개발을 훨씬 쉽게 만듭니다.

2. ESLint 규칙 활용: eslint-plugin-react의 ‘react/jsx-key’ 규칙을 활성화하여 key 누락을 자동으로 감지하세요.

// .eslintrc.js
module.exports = {
  rules: {
    'react/jsx-key': 'error'
  }
};

3. TypeScript 사용: TypeScript를 사용하면 데이터 구조를 명확히 정의하여 key로 사용할 속성을 쉽게 파악할 수 있습니다.

4. 코드 리뷰 체크리스트: 코드 리뷰 시 map() 함수를 사용하는 모든 곳에서 적절한 key가 있는지 확인하세요.

5. 성능 모니터링: React DevTools를 사용하여 불필요한 리렌더링이 발생하지 않는지 확인하세요. 잘못된 key 사용은 성능 저하의 주요 원인입니다.

마무리

“Warning: Each child in a list should have a unique “key” prop” 에러는 React 개발에서 매우 흔하게 발생하지만, 올바르게 이해하고 대응하면 쉽게 해결할 수 있습니다. 단순히 경고를 없애는 것이 목적이 아니라, React의 재조정 알고리즘을 이해하고 성능을 최적화하는 것이 중요합니다. 항상 고유하고 안정적인 key를 사용하고, 인덱스 사용은 최대한 피하세요. 이 가이드를 참고하여 더 나은 React 애플리케이션을 개발하시기 바랍니다. 문제가 지속되면 React 공식 문서와 커뮤니티를 참고하시면 더 많은 도움을 받을 수 있습니다.