Blog

도입

React 개발 중 “Warning: Each child in a list should have a unique “key” prop” 경고 메시지를 만나본 적이 있으신가요? 이는 React 개발자라면 누구나 한 번쯤 마주치는 가장 흔한 경고 메시지 중 하나입니다. 이 경고는 리스트를 렌더링할 때 각 요소에 고유한 key prop이 없을 때 발생합니다. 겉보기에는 단순한 경고처럼 보이지만, 무시하면 애플리케이션의 성능 저하와 예상치 못한 버그를 유발할 수 있습니다. 이 글에서는 이 경고가 왜 발생하는지, 어떻게 해결하는지, 그리고 올바른 key 사용법까지 완벽하게 알아보겠습니다.

에러 상세 분석

“Warning: Each child in a list should have a unique “key” prop” 경고는 React가 가상 DOM을 효율적으로 업데이트하기 위해 필요한 정보가 누락되었을 때 표시됩니다. React는 리스트의 각 항목을 식별하기 위해 key를 사용하는데, 이를 통해 어떤 항목이 변경, 추가, 삭제되었는지 빠르게 파악합니다. key가 없으면 React는 모든 항목을 처음부터 다시 렌더링해야 하므로 성능이 크게 저하됩니다. 또한 리스트 항목의 상태가 잘못 유지되거나, 입력 필드의 값이 뒤섞이는 등의 문제가 발생할 수 있습니다. 이 경고는 개발 모드에서만 표시되지만, 프로덕션 환경에서도 동일한 문제가 존재하므로 반드시 해결해야 합니다. key는 형제 요소들 사이에서만 고유하면 되며, 전역적으로 고유할 필요는 없습니다.

발생 원인 5가지

1. key prop 완전 누락

가장 기본적인 원인은 배열을 map으로 렌더링할 때 key를 아예 지정하지 않는 경우입니다. JSX에서 배열을 순회하며 컴포넌트를 생성할 때는 반드시 key가 필요합니다.

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

많은 개발자들이 배열의 index를 key로 사용하는데, 이는 임시방편일 뿐 권장되지 않습니다. 리스트의 순서가 바뀌거나 항목이 추가/삭제되면 인덱스가 변경되어 React가 요소를 올바르게 추적할 수 없게 됩니다.

3. 중복된 key 값 사용

여러 항목이 동일한 key 값을 가지는 경우도 이 경고를 유발합니다. key는 반드시 형제 요소들 사이에서 고유해야 하며, 같은 값이 중복되면 React가 요소를 구분할 수 없습니다.

4. 동적으로 생성되는 key

Math.random()이나 Date.now()처럼 렌더링할 때마다 변경되는 값을 key로 사용하면, React가 매번 새로운 요소로 인식하여 불필요한 재렌더링이 발생합니다.

5. Fragment에 key 누락

React.Fragment를 사용할 때도 리스트 내에서 사용된다면 key가 필요합니다. 단축 문법 <>…</>는 key를 받을 수 없으므로 <React.Fragment> 형태로 작성해야 합니다.

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

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

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

const items = [
  { id: 1, name: '사과' },
  { id: 2, name: '바나나' },
  { id: 3, name: '오렌지' }
];

function FruitList() {
  return (
    

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

2. 복합 key 생성

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

const orders = [
  { userId: 1, productId: 101, quantity: 2 },
  { userId: 1, productId: 102, quantity: 1 },
  { userId: 2, productId: 101, quantity: 3 }
];

function OrderList() {
  return (
    

      {orders.map(order => (
        

          User {order.userId}: Product {order.productId} x {order.quantity}
        
      ))}
    
  );
}

3. 외부 라이브러리로 UUID 생성

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

import { v4 as uuidv4 } from 'uuid';

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

function FruitList() {
  return (
    

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

4. 데이터 전처리 시 ID 추가

API 응답이나 외부 데이터를 받을 때 ID가 없다면, 전처리 단계에서 고유 ID를 추가하는 것이 좋습니다.

const rawData = ['사과', '바나나', '오렌지'];
const processedData = rawData.map((item, index) => ({
  id: `fruit-${index}-${item}`,
  name: item
}));

function FruitList() {
  return (
    

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

5. Fragment에 key 추가

여러 요소를 그룹화할 때 Fragment를 사용한다면, 완전한 형태로 작성하여 key를 추가해야 합니다.

function TableRows({ data }) {
  return (
    <>
      {data.map(item => (
        
          
            {item.name}
          
          
            {item.description}
          
        
      ))}
    
  );
}

6. 중첩 리스트 처리

리스트 안에 또 다른 리스트가 있는 경우, 각 레벨마다 고유한 key를 지정해야 합니다.

const categories = [
  { id: 1, name: '과일', items: [{ id: 101, name: '사과' }, { id: 102, name: '바나나' }] },
  { id: 2, name: '채소', items: [{ id: 201, name: '당근' }, { id: 202, name: '양파' }] }
];

function CategoryList() {
  return (
    

      {categories.map(category => (
        

          
{category.name}
          

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

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

정적이고 재정렬되지 않으며 항목이 추가/삭제되지 않는 리스트에서만 인덱스를 key로 사용할 수 있습니다.

const staticMenu = ['홈', '소개', '서비스', '연락처'];

function Navigation() {
  return (
    
  );
}

예방법과 베스트 프랙티스

1. 데이터 설계 시 ID 포함: 백엔드에서 데이터를 설계할 때부터 각 항목에 고유 ID를 포함시키세요. 데이터베이스의 기본 키나 UUID를 활용하면 좋습니다.

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

3. key 값의 안정성 보장: key는 렌더링 간에 안정적이고 예측 가능해야 합니다. 렌더링할 때마다 변경되는 값은 사용하지 마세요.

4. 형제 간 고유성만 보장: key는 전역적으로 고유할 필요는 없고, 같은 부모 아래의 형제 요소들 사이에서만 고유하면 됩니다.

5. 컴포넌트 재사용 시 주의: 동일한 컴포넌트를 여러 곳에서 재사용할 때, 각 위치에서 사용되는 데이터의 key가 충돌하지 않도록 주의하세요.

마무리

“Warning: Each child in a list should have a unique “key” prop” 경고는 React의 효율적인 렌더링을 위한 중요한 신호입니다. 단순히 경고를 없애는 것이 목적이 아니라, React의 Virtual DOM 메커니즘을 올바르게 활용하여 성능을 최적화하고 버그를 예방하는 것이 핵심입니다. 고유하고 안정적인 ID를 key로 사용하는 습관을 들이면, 더욱 견고하고 효율적인 React 애플리케이션을 개발할 수 있습니다. 이 글에서 소개한 해결 방법들을 프로젝트에 적용하여 깔끔한 코드를 작성하시기 바랍니다.