React의 useId 훅: 안정적이고 고유한 식별자 생성을 위한 심층 분석

끊임없이 발전하는 웹 개발 환경에서 서버 렌더링 콘텐츠와 클라이언트 사이드 애플리케이션 간의 일관성을 보장하는 것은 매우 중요합니다. 개발자들이 직면해 온 가장 끈질기고 미묘한 문제 중 하나는 고유하고 안정적인 식별자를 생성하는 것이었습니다. 이러한 ID는 레이블을 입력에 연결하고, 접근성을 위해 ARIA 속성을 관리하며, 기타 여러 DOM 관련 작업에 필수적입니다. 수년 동안 개발자들은 차선책에 의존했으며, 이는 종종 하이드레이션 불일치와 골치 아픈 버그로 이어졌습니다. 바로 이때 React 18의 `useId` 훅이 등장했습니다. 이 문제는 간단하면서도 강력한 해결책으로, 이 문제를 우아하고 결정적으로 해결하도록 설계되었습니다.

이 종합 가이드는 전 세계의 React 개발자를 위한 것입니다. 간단한 클라이언트 렌더링 애플리케이션을 구축하든, Next.js와 같은 프레임워크로 복잡한 서버 사이드 렌더링(SSR) 경험을 만들든, 전 세계가 사용할 컴포넌트 라이브러리를 작성하든, `useId`를 이해하는 것은 더 이상 선택이 아닙니다. 이것은 현대적이고 견고하며 접근성 높은 React 애플리케이션을 구축하기 위한 기본 도구입니다.

`useId` 이전의 문제: 하이드레이션 불일치의 세계

`useId`의 진가를 제대로 이해하려면, 먼저 그것이 없었던 세계를 이해해야 합니다. 핵심 문제는 항상 렌더링된 페이지 내에서 고유하면서도 서버와 클라이언트 간에 일관성 있는 ID가 필요하다는 것이었습니다.

간단한 폼 입력 컴포넌트를 생각해 보세요:

function LabeledInput({ label, ...props }) {
  // 여기서 어떻게 고유 ID를 생성할까요?
  const inputId = 'some-unique-id';

  return (
    

      {label}
      
    
  );
}

``의 `htmlFor` 속성은 시맨틱 HTML과 접근성을 위해 ``의 `id`와 일치해야 합니다. 만약 이 `LabeledInput` 컴포넌트를 한 페이지에서 여러 번 사용한다면, 각 인스턴스마다 다른 ID가 필요합니다.

시도 1: `Math.random()` 사용하기

고유 ID를 생성할 때 가장 먼저 떠올리는 흔한 생각은 무작위성을 이용하는 것입니다.

// 안티패턴: 이렇게 사용하지 마세요!
const inputId = `input-${Math.random()}`;

이 방법이 실패하는 이유:

• SSR 불일치: 서버는 하나의 랜덤 숫자(예: `input-0.12345`)를 생성합니다. 클라이언트가 애플리케이션을 하이드레이션할 때, 자바스크립트를 다시 실행하여 다른 랜덤 숫자(예: `input-0.67890`)를 생성합니다. React는 서버 HTML과 클라이언트 렌더링 HTML 간의 이러한 불일치를 보고 하이드레이션 오류를 발생시킵니다.
• 리렌더링: 이 ID는 컴포넌트가 리렌더링될 때마다 변경되어 예상치 못한 동작과 성능 문제를 일으킬 수 있습니다.

시도 2: 전역 카운터 사용하기

조금 더 정교한 접근 방식은 간단한 증가 카운터를 사용하는 것입니다.

// 안티패턴: 이 또한 문제가 있습니다
let globalCounter = 0;
function generateId() {
  globalCounter++;
  return `component-${globalCounter}`;
}

이 방법이 실패하는 이유:

• SSR 순서 의존성: 처음에는 작동하는 것처럼 보일 수 있습니다. 서버가 특정 순서로 컴포넌트를 렌더링하고 클라이언트가 이를 하이드레이션합니다. 하지만 서버와 클라이언트 간의 컴포넌트 렌더링 순서가 약간 다르다면 어떨까요? 이는 코드 분할이나 순서가 다른 스트리밍에서 발생할 수 있습니다. 만약 컴포넌트가 서버에서는 렌더링되었지만 클라이언트에서는 지연된다면, 생성된 ID의 순서가 동기화되지 않아 다시 하이드레이션 불일치를 초래할 수 있습니다.
• 컴포넌트 라이브러리의 지옥: 라이브러리 제작자라면 페이지의 다른 많은 컴포넌트들이 자체적인 전역 카운터를 사용할 수 있다는 점을 제어할 수 없습니다. 이는 라이브러리와 호스트 애플리케이션 간의 ID 충돌로 이어질 수 있습니다.

이러한 문제들은 컴포넌트 트리의 구조를 이해하는 React 네이티브의 결정론적 솔루션이 필요함을 부각시켰습니다. 이것이 바로 `useId`가 제공하는 것입니다.

`useId` 소개: 공식적인 해결책

`useId` 훅은 서버와 클라이언트 렌더링 모두에서 안정적인 고유 문자열 ID를 생성합니다. 이것은 접근성 속성에 전달할 ID를 생성하기 위해 컴포넌트의 최상위 레벨에서 호출되도록 설계되었습니다.

핵심 문법 및 사용법

문법은 더할 나위 없이 간단합니다. 인자를 받지 않으며 문자열 ID를 반환합니다.

import { useId } from 'react';

function LabeledInput({ label, ...props }) {
  // useId()는 ":r0:"와 같은 고유하고 안정적인 ID를 생성합니다
  const id = useId();

  return (
    

      {label}
      
    
  );
}

// 사용 예시
function App() {
  return (
    

      
회원가입 폼
      
      
    
  );
}

이 예제에서 첫 번째 `LabeledInput`은 `":r0:"`와 같은 ID를, 두 번째는 `":r1:"`와 같은 ID를 얻을 수 있습니다. ID의 정확한 형식은 React의 구현 세부 사항이며 의존해서는 안 됩니다. 유일한 보장은 그것이 고유하고 안정적이라는 것입니다.

핵심은 React가 서버와 클라이언트에서 동일한 순서의 ID가 생성되도록 보장하여, 생성된 ID와 관련된 하이드레이션 오류를 완전히 제거한다는 것입니다.

개념적으로 어떻게 작동하는가?

`useId`의 마법은 그 결정론적 특성에 있습니다. 무작위성을 사용하지 않습니다. 대신, React 컴포넌트 트리 내에서 컴포넌트의 경로를 기반으로 ID를 생성합니다. 컴포넌트 트리 구조는 서버와 클라이언트에서 동일하기 때문에 생성된 ID는 일치함이 보장됩니다. 이 접근 방식은 전역 카운터 방법의 실패 원인이었던 컴포넌트 렌더링 순서에 영향을 받지 않습니다.

하나의 훅 호출로 여러 관련 ID 생성하기

하나의 컴포넌트 내에서 여러 관련 ID를 생성해야 하는 경우가 많습니다. 예를 들어, 입력 필드는 자신을 위한 ID와 `aria-describedby`를 통해 연결된 설명 요소를 위한 또 다른 ID가 필요할 수 있습니다.

`useId`를 여러 번 호출하고 싶을 수 있습니다:

// 권장되지 않는 패턴
const inputId = useId();
const descriptionId = useId();

이 방법도 작동하지만, 권장되는 패턴은 컴포넌트당 `useId`를 한 번만 호출하고 반환된 기본 ID를 필요한 다른 ID의 접두사로 사용하는 것입니다.

import { useId } from 'react';

function FormFieldWithDescription({ label, description }) {
  const baseId = useId();
  const inputId = `${baseId}-input`;
  const descriptionId = `${baseId}-description`;

  return (
    

      {label}
      
      

        {description}
      
    
  );
}

이 패턴이 더 좋은 이유:

• 효율성: 이 컴포넌트 인스턴스에 대해 React가 생성하고 추적해야 하는 고유 ID가 하나뿐임을 보장합니다.
• 명확성과 시맨틱: 요소들 간의 관계를 명확하게 만듭니다. 코드를 읽는 사람은 누구나 `form-field-:r2:-input`과 `form-field-:r2:-description`이 함께 속한다는 것을 알 수 있습니다.
• 고유성 보장: `baseId`가 애플리케이션 전체에서 고유함이 보장되므로, 접미사가 붙은 모든 문자열도 고유합니다.

가장 강력한 기능: 완벽한 서버 사이드 렌더링 (SSR)

`useId`가 해결하기 위해 만들어진 핵심 문제인 Next.js, Remix, 또는 Gatsby와 같은 SSR 환경에서의 하이드레이션 불일치를 다시 살펴보겠습니다.

시나리오: 하이드레이션 불일치 오류

Next.js 애플리케이션에서 우리의 오래된 `Math.random()` 접근 방식을 사용하는 컴포넌트를 상상해 보세요.

1. 서버 렌더링: 서버가 컴포넌트 코드를 실행합니다. `Math.random()`은 `0.5`를 생성합니다. 서버는 브라우저에 ``가 포함된 HTML을 보냅니다.
2. 클라이언트 렌더링 (하이드레이션): 브라우저는 HTML과 자바스크립트 번들을 받습니다. React가 클라이언트에서 시작되고 이벤트 리스너를 붙이기 위해 컴포넌트를 다시 렌더링합니다(이 과정을 하이드레이션이라고 합니다). 이 렌더링 동안 `Math.random()`은 `0.9`를 생성합니다. React는 ``를 가진 가상 DOM을 생성합니다.
3. 불일치 발생: React는 서버에서 생성된 HTML(`id="input-0.5"`)과 클라이언트에서 생성된 가상 DOM(`id="input-0.9"`)을 비교합니다. 차이점을 발견하고 경고를 발생시킵니다: "Warning: Prop `id` did not match. Server: "input-0.5" Client: "input-0.9"".

이것은 단순한 경고가 아닙니다. 깨진 UI, 잘못된 이벤트 처리, 그리고 나쁜 사용자 경험으로 이어질 수 있습니다. React는 서버에서 렌더링된 HTML을 버리고 전체 클라이언트 사이드 렌더링을 수행해야 할 수도 있으며, 이는 SSR의 성능 이점을 무효화합니다.

시나리오: `useId` 해결책

이제 `useId`가 이 문제를 어떻게 해결하는지 봅시다.

1. 서버 렌더링: 서버가 컴포넌트를 렌더링합니다. `useId`가 호출됩니다. 트리 내 컴포넌트의 위치를 기반으로 안정적인 ID, 예를 들어 `":r5:"`를 생성합니다. 서버는 ``가 포함된 HTML을 보냅니다.
2. 클라이언트 렌더링 (하이드레이션): 브라우저가 HTML과 자바스크립트를 받습니다. React가 하이드레이션을 시작합니다. 트리 내 동일한 위치에서 동일한 컴포넌트를 렌더링합니다. `useId` 훅이 다시 실행됩니다. 그 결과는 트리 구조에 따라 결정론적이므로, 정확히 동일한 ID인 `":r5:"`를 생성합니다.
3. 완벽한 일치: React는 서버에서 생성된 HTML(`id=":r5:"`)과 클라이언트에서 생성된 가상 DOM(`id=":r5:"`)을 비교합니다. 완벽하게 일치합니다. 하이드레이션이 오류 없이 성공적으로 완료됩니다.

이 안정성은 `useId`의 가치 제안의 초석입니다. 이전에는 불안정했던 과정에 신뢰성과 예측 가능성을 가져다줍니다.

`useId`를 통한 접근성(a11y) 초능력

`useId`는 SSR에 중요하지만, 일상적인 주요 사용처는 접근성을 향상시키는 것입니다. 요소들을 올바르게 연결하는 것은 스크린 리더와 같은 보조 기술 사용자들에게 기본적입니다.

`useId`는 다양한 ARIA(Accessible Rich Internet Applications) 속성을 연결하는 데 완벽한 도구입니다.

예제: 접근성 있는 모달 대화 상자

모달 대화 상자는 스크린 리더가 제목과 설명을 올바르게 안내할 수 있도록 주 컨테이너를 제목 및 설명과 연결해야 합니다.

import { useId, useState } from 'react';

function AccessibleModal({ title, children }) {
  const id = useId();
  const titleId = `${id}-title`;
  const contentId = `${id}-content`;

  return (
    

      
{title}
      

        {children}
      
    
  );
}

function App() {
  return (
    
      
본 서비스를 이용함으로써 귀하는 당사의 이용 약관에 동의하는 것입니다...
    
  );
}

여기서 `useId`는 이 `AccessibleModal`이 어디에서 사용되든 `aria-labelledby`와 `aria-describedby` 속성이 제목과 내용 요소의 정확하고 고유한 ID를 가리키도록 보장합니다. 이는 스크린 리더 사용자에게 원활한 경험을 제공합니다.

예제: 그룹 내 라디오 버튼 연결하기

복잡한 폼 컨트롤은 종종 신중한 ID 관리가 필요합니다. 라디오 버튼 그룹은 공통된 레이블과 연결되어야 합니다.

import { useId } from 'react';

function RadioGroup() {
  const id = useId();
  const headingId = `${id}-heading`;

  return (
    

      
글로벌 배송 옵션을 선택하세요:
      

        
        일반 배송 (5-10 영업일)
      
      

        
        특급 배송 (2-3 영업일)
      
    
  );
}

단일 `useId` 호출을 접두사로 사용함으로써, 우리는 어디서든 안정적으로 작동하는 응집력 있고 접근성이 높으며 고유한 컨트롤 세트를 만듭니다.

중요한 구분: `useId`의 용도가 아닌 것

큰 힘에는 큰 책임이 따릅니다. `useId`를 사용하지 않아야 할 곳을 이해하는 것도 마찬가지로 중요합니다.

리스트 키에 `useId`를 사용하지 마세요

이것은 개발자들이 저지르는 가장 흔한 실수입니다. React 키는 컴포넌트 인스턴스가 아닌 특정 데이터 조각에 대한 안정적이고 고유한 식별자여야 합니다.

잘못된 사용법:

function TodoList({ todos }) {
  // 안티패턴: 키에 절대 useId를 사용하지 마세요!
  return (
    

      {todos.map(todo => {
        const key = useId(); // 이것은 잘못되었습니다!
        return 
{todo.text}
;
      })}
    
  );
}

이 코드는 훅의 규칙(루프 안에서 훅을 호출할 수 없음)을 위반합니다. 하지만 구조를 다르게 하더라도 논리는 결함이 있습니다. `key`는 `todo` 아이템 자체, 예를 들어 `todo.id`와 연결되어야 합니다. 이를 통해 React는 아이템이 추가, 제거 또는 재정렬될 때 올바르게 추적할 수 있습니다.

키에 `useId`를 사용하면 데이터가 아닌 렌더링 위치(예: 첫 번째 `

function TodoList({ todos }) {
  return (
    

      {todos.map(todo => (
        // 올바른 방법: 데이터에서 ID를 사용하세요.
        
{todo.text}
      ))}
    
  );
}