Blog

React에서 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는 Virtual DOM을 효율적으로 업데이트하기 위해 각 리스트 아이템을 식별할 수 있는 key가 필요하며, 이것이 없으면 전체 리스트를 다시 렌더링하게 되어 성능이 크게 저하됩니다.

에러 상세 분석

이 경고 메시지는 React의 재조정(Reconciliation) 알고리즘과 밀접한 관련이 있습니다. React는 컴포넌트가 업데이트될 때 이전 가상 DOM 트리와 새로운 가상 DOM 트리를 비교하여 실제 DOM에 필요한 최소한의 변경만 적용합니다. 리스트를 렌더링할 때 key prop은 React가 어떤 아이템이 변경, 추가, 삭제되었는지 식별하는 힌트를 제공합니다. key가 없으면 React는 리스트의 모든 요소를 순서대로 비교하게 되어 비효율적입니다. 예를 들어, 리스트의 첫 번째 위치에 새로운 아이템을 추가하면 key가 없을 경우 모든 후속 아이템이 다시 렌더링됩니다. 또한 key가 없거나 중복되면 컴포넌트 상태가 잘못 유지되거나 예상치 못한 동작이 발생할 수 있습니다. 이는 특히 입력 필드나 상태를 가진 컴포넌트를 렌더링할 때 심각한 버그로 이어질 수 있습니다.

에러 발생 원인 5가지

1. key prop 완전히 누락

가장 흔한 원인은 map 함수로 배열을 렌더링할 때 key prop을 아예 제공하지 않는 경우입니다. 초보 개발자들이 자주 범하는 실수로, React가 리스트 아이템을 식별할 방법이 전혀 없게 됩니다.

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

배열의 인덱스(index)를 key로 사용하는 것은 일시적으로 경고를 없앨 수는 있지만, 리스트의 순서가 변경되거나 아이템이 추가/삭제될 때 심각한 문제를 일으킵니다. 인덱스는 아이템의 고유성을 보장하지 않기 때문입니다.

3. 중복된 key 값 사용

여러 아이템이 같은 key 값을 가지면 React는 이들을 구별할 수 없습니다. 이는 데이터베이스에서 가져온 ID가 중복되거나, 잘못된 데이터 구조를 사용할 때 발생합니다.

4. 동적으로 생성된 불안정한 key

Math.random()이나 Date.now()처럼 렌더링할 때마다 변경되는 값을 key로 사용하면, React가 아이템을 추적할 수 없어 매번 전체를 다시 렌더링하게 됩니다.

5. Fragment에 key 누락

React.Fragment를 사용하여 여러 요소를 그룹화할 때도 리스트 내에 있다면 key가 필요합니다. 단축 문법인 <>…</>는 key를 지원하지 않으므로 <React.Fragment key={…}>를 사용해야 합니다.

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

방법 1: 고유한 ID를 key로 사용

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

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

function UserList() {
  return (
    

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

방법 2: 여러 속성을 조합하여 고유 key 생성

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

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

function PostList() {
  return (
    

      {posts.map(post => (
        

          
{post.title}
        
      ))}
    
  );
}

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

데이터에 고유 ID가 없고 생성할 수도 없는 경우, 데이터를 처음 로드할 때 UUID를 할당합니다.

import { v4 as uuidv4 } from 'uuid';

function TodoList({ initialTodos }) {
  const [todos, setTodos] = useState(
    initialTodos.map(todo => ({ ...todo, id: uuidv4() }))
  );

  return (
    

      {todos.map(todo => (
        
{todo.text}
      ))}
    
  );
}

방법 4: 인덱스 사용 (정적 리스트에만 적용)

리스트가 절대 변경되지 않고, 순서도 바뀌지 않으며, 필터링되지 않는다면 인덱스를 key로 사용할 수 있습니다.

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

function Navigation() {
  return (
    
  );
}

방법 5: Fragment에 key 추가

Fragment를 사용할 때는 전체 문법으로 key를 추가해야 합니다.

import React from 'react';

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

방법 6: 중첩된 리스트 처리

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

function NestedList({ categories }) {
  return (
    

      {categories.map(category => (
        

          
{category.name}
          

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

방법 7: 조건부 렌더링과 key

조건부로 렌더링되는 리스트 아이템에도 key가 필요합니다.

function FilteredList({ items, showActive }) {
  const filteredItems = items.filter(item => 
    showActive ? item.active : true
  );

  return (
    

      {filteredItems.map(item => (
        

          {item.name} {item.active && '(활성)'}
        
      ))}
    
  );
}

예방법과 베스트 프랙티스

Warning: Each child in a list should have a unique “key” prop 에러를 예방하려면 몇 가지 베스트 프랙티스를 따라야 합니다. 첫째, 데이터 모델 설계 단계에서 모든 리스트 아이템에 고유 식별자를 포함시키세요. 데이터베이스에서 가져온 데이터라면 primary key를 사용하고, 클라이언트에서 생성한 데이터라면 UUID를 할당하세요. 둘째, ESLint의 react/jsx-key 규칙을 활성화하여 key 누락을 자동으로 감지하세요. 셋째, 컴포넌트를 작성할 때 map 함수를 사용하는 즉시 key prop을 추가하는 습관을 들이세요. 넷째, 코드 리뷰 시 key prop의 적절성을 확인하세요. 마지막으로, 성능 최적화가 필요한 큰 리스트의 경우 react-window나 react-virtualized 같은 가상화 라이브러리를 고려하되, 이 경우에도 올바른 key 사용은 필수입니다.

마무리

React의 “Warning: Each child in a list should have a unique “key” prop” 에러는 단순해 보이지만, 애플리케이션의 성능과 안정성에 큰 영향을 미칩니다. 이 글에서 소개한 원인 분석과 7가지 해결 방법을 통해 에러를 완전히 이해하고 해결할 수 있을 것입니다. 고유하고 안정적인 key를 사용하는 것은 React의 재조정 알고리즘을 최대한 활용하여 최적의 성능을 달성하는 핵심입니다. 오늘부터 모든 리스트 렌더링에 적절한 key를 사용하여 깨끗하고 효율적인 React 코드를 작성하세요.