Blog

React 개발 중 가장 흔하게 만나는 경고 메시지

React 애플리케이션을 개발하다 보면 콘솔 창에서 “Warning: Each child in a list should have a unique “key” prop”라는 경고 메시지를 자주 접하게 됩니다. 이 경고는 React에서 리스트 렌더링 시 각 요소를 효율적으로 관리하기 위해 필요한 key prop이 누락되었거나 올바르지 않을 때 발생합니다. 비록 애플리케이션이 정상적으로 작동하더라도, 이 경고를 무시하면 성능 저하와 예상치 못한 버그가 발생할 수 있습니다. 따라서 이 문제를 정확히 이해하고 올바르게 해결하는 것이 중요합니다. 이 글에서는 Warning: Each child in a list should have a unique “key” prop 에러의 원인부터 해결 방법, 그리고 예방법까지 상세하게 다루겠습니다.

에러 상세 분석

이 경고 메시지는 React의 재조정(Reconciliation) 알고리즘과 밀접한 관련이 있습니다. React는 가상 DOM을 사용하여 실제 DOM 업데이트를 최소화하는데, 리스트의 각 항목을 추적하기 위해 key prop을 사용합니다. key는 React가 어떤 항목이 변경, 추가, 또는 삭제되었는지 식별하는 데 도움을 줍니다.

key prop이 없거나 중복되면 React는 리스트의 각 요소를 정확히 구분할 수 없게 됩니다. 이로 인해 컴포넌트의 상태가 잘못 유지되거나, 불필요한 DOM 조작이 발생하여 성능이 저하될 수 있습니다. 특히 리스트의 순서가 변경되거나 항목이 동적으로 추가/삭제되는 경우, key가 없으면 예상치 못한 렌더링 문제가 발생할 수 있습니다.

이 경고는 개발 모드에서만 표시되지만, 프로덕션 환경에서도 동일한 문제가 존재합니다. 따라서 개발 단계에서 반드시 해결해야 하는 중요한 이슈입니다.

발생 원인 5가지

1. key prop 완전히 누락

가장 기본적인 원인은 배열을 map 함수로 렌더링할 때 key prop을 아예 제공하지 않는 경우입니다. 초보 개발자들이 가장 자주 범하는 실수입니다.

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

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

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

배열의 인덱스를 key로 사용하는 것은 간편해 보이지만, 리스트의 순서가 변경되거나 항목이 추가/삭제될 때 문제를 일으킵니다. 인덱스는 항목의 고유성을 보장하지 않기 때문입니다.

3. 중복된 key 값 사용

데이터베이스에서 가져온 데이터 중 중복된 ID가 있거나, 같은 값을 여러 항목의 key로 사용하는 경우입니다. React는 각 key가 형제 요소 간에 고유해야 한다고 요구합니다.

4. Fragment 내부의 리스트 항목

React.Fragment나 <> 단축 문법을 사용할 때, Fragment로 감싼 여러 요소에 key를 제공하지 않으면 경고가 발생합니다. Fragment에도 key prop을 전달해야 합니다.

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

중첩된 배열을 렌더링할 때, 외부 리스트에만 key를 제공하고 내부 리스트에는 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 또는 nanoid 라이브러리 사용

데이터에 고유 ID가 없는 경우, 라이브러리를 사용하여 고유 키를 생성할 수 있습니다.

import { nanoid } from 'nanoid';

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

return (
  

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

3. 복합 키 생성

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

const posts = [
  { userId: 1, postId: 101, title: '첫 번째 글' },
  { userId: 2, postId: 102, title: '두 번째 글' }
];

return (
  

    {posts.map(post => (
      

        
{post.title}
      
    ))}
  
);

4. Fragment에 key 추가

Fragment를 사용할 때는 완전한 문법으로 key를 전달해야 합니다.

import React from 'react';

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

return (
  

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

5. 중첩된 리스트 처리

중첩된 리스트에서는 각 레벨마다 고유한 key를 제공해야 합니다.

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

return (
  

    {categories.map(category => (
      

        
{category.name}
        

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

6. 조건부 렌더링에서 key 사용

조건에 따라 다른 컴포넌트를 렌더링할 때도 key를 활용할 수 있습니다.

const notifications = [
  { id: 1, type: 'success', message: '성공했습니다' },
  { id: 2, type: 'error', message: '오류가 발생했습니다' }
];

return (
  

    {notifications.map(notif => (
      

        {notif.message}
      
    ))}
  
);

7. 인덱스를 key로 사용해도 되는 경우

리스트가 정적이고 재정렬되지 않으며, 항목에 고유 ID가 없는 경우에만 인덱스를 사용할 수 있습니다.

// 정적 리스트의 경우에만 사용
const staticMenu = ['홈', '소개', '연락처'];

return (
  
);

예방법과 베스트 프랙티스

데이터 구조 설계 시 고유 ID 포함

백엔드에서 데이터를 가져올 때 항상 고유한 ID 필드를 포함하도록 설계합니다. 데이터베이스의 primary key나 UUID를 활용하세요.

ESLint 규칙 활용

eslint-plugin-react의 ‘react/jsx-key’ 규칙을 활성화하여 key 누락을 자동으로 감지할 수 있습니다. 이를 통해 코드 작성 단계에서 바로 경고를 받을 수 있습니다.

컴포넌트 재사용 시 key 전달

재사용 가능한 컴포넌트를 만들 때, 리스트 항목으로 사용될 경우를 대비해 key prop을 받을 수 있도록 설계합니다.

성능 최적화 고려

key를 올바르게 사용하면 React.memo나 useMemo와 함께 사용하여 불필요한 리렌더링을 방지할 수 있습니다. 안정적인 key는 성능 최적화의 기초가 됩니다.

마무리

Warning: Each child in a list should have a unique “key” prop 경고는 React 개발에서 매우 흔하지만, 올바르게 이해하고 해결하면 애플리케이션의 성능과 안정성을 크게 향상시킬 수 있습니다. 고유하고 안정적인 key를 사용하는 것은 단순히 경고를 제거하는 것 이상의 의미를 가집니다. 이는 React의 재조정 알고리즘이 효율적으로 작동하도록 하여 사용자 경험을 개선하는 핵심 요소입니다. 이 글에서 소개한 해결 방법과 베스트 프랙티스를 실무에 적용하여 더 나은 React 애플리케이션을 개발하시기 바랍니다.