도입: React 개발자라면 반드시 마주치는 에러

React 개발을 하다 보면 콘솔 창에서 “Warning: Each child in a list should have a unique “key” prop” 경고 메시지를 자주 마주치게 됩니다. 이 경고는 React의 리스트 렌더링 과정에서 발생하는 가장 흔한 문제 중 하나로, 초보 개발자뿐만 아니라 경험 있는 개발자들도 종종 간과하는 부분입니다. 이 에러는 애플리케이션의 성능 저하와 예상치 못한 UI 버그를 야기할 수 있어 반드시 해결해야 하는 중요한 문제입니다. 본 가이드에서는 이 경고가 발생하는 근본적인 원인부터 실전에서 바로 적용할 수 있는 해결 방법, 그리고 미래에 같은 문제를 예방하는 베스트 프랙티스까지 모든 것을 다룹니다.

에러 상세 분석: 왜 이 경고가 발생할까?

“Warning: Each child in a list should have a unique “key” prop” 경고는 React가 가상 DOM(Virtual DOM)을 효율적으로 업데이트하기 위해 필요한 key 속성이 누락되었거나 부적절하게 사용되었을 때 발생합니다. React는 리스트의 각 요소를 추적하고 변경 사항을 감지하기 위해 key를 사용합니다. key가 없거나 중복되면 React는 어떤 요소가 추가, 삭제, 수정되었는지 정확히 파악할 수 없어 전체 리스트를 다시 렌더링하게 됩니다.

이는 단순한 경고처럼 보이지만, 실제로는 다음과 같은 문제를 초래할 수 있습니다:

• 성능 저하: 불필요한 전체 리스트 재렌더링으로 인한 성능 문제
• 상태 관리 오류: 컴포넌트 상태가 잘못된 요소에 유지되는 현상
• UI 버그: 입력 필드의 값이 잘못된 항목에 표시되는 등의 문제
• 애니메이션 문제: 리스트 아이템의 부드러운 전환 효과 실패

발생 원인 5가지

1. key 속성 완전 누락

가장 기본적인 원인으로, 배열을 map() 함수로 렌더링할 때 key 속성을 아예 추가하지 않은 경우입니다. 많은 초보 개발자들이 key의 중요성을 인지하지 못해 발생합니다.

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

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

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

배열의 인덱스를 key로 사용하는 것은 임시방편일 뿐 근본적인 해결책이 아닙니다. 리스트의 순서가 변경되거나 항목이 추가/삭제되면 인덱스가 재배정되어 React가 요소를 잘못 식별하게 됩니다. 특히 정렬, 필터링, 추가/삭제 기능이 있는 리스트에서는 심각한 버그를 유발합니다.

3. 중복된 key 값 사용

데이터베이스에서 가져온 ID가 중복되거나, 잘못된 속성을 key로 사용하여 동일한 key 값이 여러 요소에 할당되는 경우입니다. 이는 데이터 구조 설계의 문제일 수 있습니다.

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

외부 리스트에는 key를 추가했지만, 내부에 중첩된 리스트에는 key를 누락한 경우입니다. 모든 레벨의 리스트에 고유한 key가 필요합니다.

// 잘못된 예시
{categories.map(category => (
  

    
{category.name}
    {category.items.map(item => 
{item.name}
)} {/* key 누락 */}
  
))}

5. Fragment에 key 미적용

React.Fragment를 사용할 때 key를 추가해야 하는 상황에서 단축 문법 <>를 사용하면 key를 추가할 수 없습니다. 이 경우 명시적인 Fragment 문법을 사용해야 합니다.

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

방법 1: 고유 ID를 key로 사용 (가장 권장)

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

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

return (
  

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

방법 2: 복합 키 생성

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

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

return (
  

    {orders.map(order => (
      

        주문 정보: {order.productId}
      
    ))}
  
);

방법 3: uuid 라이브러리 사용

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

import { v4 as uuidv4 } from 'uuid';

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

return (
  

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

방법 4: 중첩 리스트 처리

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

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

return (
  

    {categories.map(category => (
      

        
{category.name}
        

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

방법 5: Fragment에 key 추가

Fragment를 사용할 때는 명시적 문법으로 key를 추가합니다.

import React, { Fragment } from 'react';

const data = [{ id: 1, title: '제목1', content: '내용1' }];

return (
  

    {data.map(item => (
      
        
{item.title}
        
{item.content}
      
    ))}
  
);

방법 6: 조건부 렌더링에서의 key 처리

조건부로 렌더링되는 리스트 항목에도 key를 일관되게 적용합니다.

const tasks = [
  { id: 1, name: '작업1', completed: true },
  { id: 2, name: '작업2', completed: false }
];

return (
  

    {tasks
      .filter(task => !task.completed)
      .map(task => (
        
{task.name}
      ))}
  
);

방법 7: 컴포넌트 분리로 key 관리

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

const ListItem = ({ item }) => (
  

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

const List = ({ items }) => (
  

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

예방법과 베스트 프랙티스

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

백엔드 API 설계 단계부터 모든 리스트 데이터에 고유 ID를 포함하도록 합니다. 데이터베이스의 Primary Key를 활용하거나 UUID를 생성합니다.

2. ESLint 규칙 활용

ESLint의 react/jsx-key 규칙을 활성화하여 key 누락을 자동으로 감지합니다.

// .eslintrc.json
{
  "rules": {
    "react/jsx-key": ["error", { "checkFragmentShorthand": true }]
  }
}

3. 인덱스를 key로 사용하지 않기

정적이고 순서가 절대 변하지 않는 리스트를 제외하고는 배열 인덱스를 key로 사용하지 않습니다. 항상 안정적이고 예측 가능한 고유 식별자를 사용하세요.

4. TypeScript 활용

TypeScript를 사용하여 데이터 타입에 id 속성을 필수로 정의하면 컴파일 시점에 오류를 잡을 수 있습니다.

interface Item {
  id: string | number;
  name: string;
}

const renderItems = (items: Item[]) => (
  items.map(item => 
{item.name}
)
);

5. 코드 리뷰 체크리스트에 포함

팀 차원에서 코드 리뷰 시 key 속성의 적절성을 확인하는 항목을 체크리스트에 추가합니다.

마무리

“Warning: Each child in a list should have a unique “key” prop” 경고는 React 개발에서 피할 수 없는 중요한 주제입니다. 이 경고를 단순히 무시하거나 인덱스로 임시방편을 사용하는 것이 아니라, 근본적인 원인을 이해하고 올바른 해결 방법을 적용해야 합니다. 고유한 ID를 사용하고, 데이터 설계 단계부터 key를 고려하며, ESLint와 TypeScript 같은 도구를 활용하면 이 문제를 효과적으로 예방할 수 있습니다. 올바른 key 사용은 단순히 경고를 없애는 것을 넘어 애플리케이션의 성능과 안정성을 크게 향상시키는 핵심 요소입니다.