React useId 훅: 라벨과 ARIA를 위한 고유 ID

useId는 컴포넌트 인스턴스마다 고유한 id를 반환하며, 렌더링마다 같은 id를 반환합니다. 컴포넌트가 한 페이지에 여러 번 나타날 수 있을 때, <label>을 <input>에 연결하거나 aria-describedby로 input을 힌트에 연결하는 데 사용하세요.

import { useId } from 'react';

function PasswordField({ label }) {
    const id = useId();
    const hintId = `${id}-hint`;
    return (
        <div style={{ marginBottom: 16 }}>
            <label htmlFor={id}>{label}</label>
            <br />
            <input id={id} type="password" aria-describedby={hintId} />
            <p id={hintId} style={{ margin: '4px 0', fontSize: 13, color: '#666' }}>
                At least 12 characters.
            </p>
            <code style={{ fontSize: 12 }}>
                id = {id}, hint id = {hintId}
            </code>
        </div>
    );
}

export default function App() {
    return (
        <form>
            <PasswordField label="Password" />
            <PasswordField label="Confirm password" />
        </form>
    );
}

같은 컴포넌트가 두 번 렌더링되고 서로 다른 두 id를 받으며, 각 필드 아래에 출력됩니다. "Confirm password" 텍스트를 클릭하면 그 라벨의 htmlFor가 그 input의 id와만 일치하므로 포커스가 두 번째 input으로 이동합니다. useId() 대신 id="password"를 직접 쓰면 두 라벨 모두 첫 번째 input을 가리킵니다.

문법

const id = useId();

useId는 인자를 받지 않고 문자열을 반환합니다. 다른 모든 훅처럼 컴포넌트의 최상위에서 호출하세요. 정확한 형식은 내부 사항이며 버전마다 바뀌어 왔습니다. React 18은 :r1:을 만들었고, React 19.2는 브라우저에서 처음 렌더링된 컴포넌트에는 _r_1_을, 서버에서 렌더링된 컴포넌트에는 트리 위치로 만든 _R_로 시작하는 id를 만듭니다. 절대 파싱하거나 그 모양에 의존하지 마세요.

Math.random이나 카운터를 쓰면 안 되는 이유

접근성을 위한 id는 서버가 보내는 HTML과 React가 브라우저에서 만드는 트리 사이에서 일치해야 합니다. id를 만드는 뻔한 두 방법은 모두 이 조건을 통과하지 못합니다.

// Changes on every render, and differs between server and browser
const id = 'field-' + Math.random().toString(36).slice(2);

// The server's counter keeps growing across requests, the browser starts at 0
let nextId = 0;
const id = 'field-' + nextId++;

서버 렌더링(Next.js, React Router 프레임워크 모드, 모든 hydrateRoot 구성)에서는 서버가 HTML에 id="field-4817"을 출력하고, 브라우저의 첫 렌더링은 field-0을 계산하며, React는 하이드레이션 불일치를 보고합니다. useId는 트리 안의 컴포넌트 위치에서 id를 만들며, 이 위치는 양쪽에서 똑같습니다.

서버가 없어도 렌더링 중에 만든 id는 렌더링마다 바뀔 수 있습니다. 이 예제는 서버 없이 그 차이를 보여 줍니다.

import { useId, useState } from 'react';

let nextId = 0;

function Field({ label }) {
    const stable = useId();
    const unstable = `field-${nextId++}`;
    console.log(label, 'useId:', stable, '| counter:', unstable);
    return (
        <p>
            <label htmlFor={stable}>{label}</label> <input id={stable} />
            <br />
            <small>useId: {stable}, counter: {unstable}</small>
        </p>
    );
}

export default function App() {
    const [renders, setRenders] = useState(0);
    return (
        <div>
            <button onClick={() => setRenders(renders + 1)}>Render again ({renders})</button>
            <Field label="Name" />
            <Field label="Email" />
        </div>
    );
}

버튼을 몇 번 클릭해 보세요. useId 값은 그대로인데 카운터 id는 렌더링마다 올라가므로, 이전 id를 가리키던 것(aria-describedby, 라벨)은 이제 아무것도 가리키지 않습니다. 카운터를 useState(() => nextId++)로 감싸면 리렌더링 문제는 해결되지만 서버 불일치는 해결되지 않습니다.

호출 하나로 여러 id 만들기

필드가 여러 개인 컴포넌트에 useId 호출이 여러 개 필요한 것은 아닙니다. 기본 id 하나를 만들고 요소마다 접미사를 붙이세요.

import { useId, useState } from 'react';

function SignupForm() {
    const id = useId();
    const [email, setEmail] = useState('');
    const invalid = email !== '' && !email.includes('@');

    return (
        <form onSubmit={(e) => e.preventDefault()}>
            <p>
                <label htmlFor={`${id}-name`}>Name</label>{' '}
                <input id={`${id}-name`} />
            </p>
            <p>
                <label htmlFor={`${id}-email`}>Email</label>{' '}
                <input
                    id={`${id}-email`}
                    value={email}
                    onChange={(e) => setEmail(e.target.value)}
                    aria-invalid={invalid}
                    aria-describedby={invalid ? `${id}-error` : undefined}
                />
            </p>
            {invalid && (
                <p id={`${id}-error`} style={{ color: '#c0392b' }}>
                    An email needs an @.
                </p>
            )}
            <small>Base id: {id}</small>
        </form>
    );
}

export default function App() {
    return <SignupForm />;
}

email 필드에 @가 없는 단어를 입력해 보세요. 오류가 나타나고 input의 aria-describedby가 그것을 가리키므로, input에 포커스가 가면 스크린 리더가 오류를 읽어 줍니다. App에서 <SignupForm />을 두 번 렌더링하면 각 사본이 자기만의 기본 id를 받습니다.

목록 key로는 쓰지 마세요

key와 id는 서로 다른 문제를 해결합니다. key는 렌더링 사이에 어느 항목이 어느 항목인지 React에 알려 주므로 데이터에서 와야 합니다. useId는 컴포넌트 인스턴스마다 id 하나를 주며, map 안에서 호출할 수 없습니다.

// Wrong: breaks the rules of hooks, and the key is unrelated to the item
{todos.map((todo) => <Todo key={useId()} todo={todo} />)}

// Right: the key comes from the data
{todos.map((todo) => <Todo key={todo.id} todo={todo} />)}

데이터에 id가 없다면, 렌더링 중이 아니라 항목을 만들 때(항목을 추가하는 이벤트 핸들러에서 crypto.randomUUID()) 만드세요. 목록과 key 페이지에서 key가 왜 항목과 함께 있어야 하는지 설명합니다.

한 페이지의 여러 React 루트

별개의 React 앱 두 개가 같은 페이지에서 렌더링되면 id가 충돌할 수 있습니다. 각 루트에 접두사를 주세요.

createRoot(document.getElementById('cart'), { identifierPrefix: 'cart-' });
createRoot(document.getElementById('chat'), { identifierPrefix: 'chat-' });

서버 렌더링에서는 같은 identifierPrefix를 서버 렌더러와 hydrateRoot에 모두 넘겨서 양쪽이 같은 id를 만들게 하세요.

자주 하는 실수

서버와 브라우저에서 다른 트리 렌더링하기. useId는 컴포넌트의 위치에 의존하므로, 필드 위에 typeof window === 'undefined' ? <A /> : <B /> 같은 분기가 있으면 두 렌더링 사이에 id가 밀릴 수 있습니다. 하이드레이션 동안에는 트리를 같게 유지하고, 그 뒤에 이펙트에서 바꾸세요.

id로 요소 찾기. document.getElementById(id)도 동작하지만, DOM 노드에 접근하는 React 방식은 ref이며 id가 전혀 필요 없습니다.

무작위 값으로 쓰기. 이 id는 앱 안에서 고유할 뿐 무작위가 아니며, 트리로부터 예측할 수 있습니다. 보안 토큰, 캐시 키, 세션을 넘어 저장하는 어떤 것에도 쓰지 마세요.

언제 쓸까

재사용 가능한 컴포넌트에 id 속성이 필요할 때마다 useId를 사용하세요. 여러 번 쓰이는 컴포넌트로 만든 폼 필드, aria-describedby로 연결한 툴팁, aria-labelledby를 가진 대화상자, aria-controls를 가진 탭이 그렇습니다. id가 라벨과 input을 연결하기만 한다면, id를 생략하고 input을 라벨 안에 중첩해도 됩니다(<label>Name <input /></label>). 요소를 중첩할 수 없을 때 useId를 사용하세요.