React useId의 SSR 수화 실패 모드: 트리 일치, 조건부 렌더링과 다중 루트 ID 충돌

useId는 SSR에서도 접근성 속성에 쓸 ID를 생성하지만, 서버 HTML과 클라이언트의 첫 렌더에서 컴포넌트 트리가 일치해야 같은 ID를 얻는다. 조건부로 useId를 호출하는 것은 훅 규칙 위반이고, 서버·클라이언트의 트리 차이나 다중 루트의 접두사 설정 차이는 수화 시 ID 불일치로 이어질 수 있다. (react.dev)

Summary#

useId는 SSR에서도 접근성 속성에 쓸 ID를 생성하지만, 서버 HTML과 클라이언트의 첫 렌더에서 컴포넌트 트리가 일치해야 같은 ID를 얻는다. 조건부로 useId를 호출하는 것은 훅 규칙 위반이고, 서버·클라이언트의 트리 차이나 다중 루트의 접두사 설정 차이는 수화 시 ID 불일치로 이어질 수 있다. (react.dev)

Key Points#

조건부 훅 호출: if문, 반복문, 조건부 조기 반환 뒤에서 useId를 호출하지 않는다. 훅은 컴포넌트 최상위에서 호출하고, 조건에 따라 필드가 필요하다면 필드를 별도 컴포넌트로 분리해 그 안에서 호출한다. 이는 우선 훅 규칙 위반이며, 단순한 수화 경고와 같은 문제로 취급해서는 안 된다. (react.dev)
서버·클라이언트 트리 불일치: useId는 호출 컴포넌트의 부모 경로를 바탕으로 ID를 만든다. 따라서 브라우저 환경 검사, 브라우저 전용 API 또는 서로 다른 초기 데이터 때문에 첫 렌더의 트리가 달라지면 생성 ID도 일치하지 않을 수 있다. 특히 <label htmlFor>와 <input id>처럼 연결된 속성을 서버 HTML과 수화 후 DOM에서 함께 확인한다. (react.dev)
다중 루트: 같은 페이지의 독립적인 React 루트에는 서로 다른 identifierPrefix를 지정해 ID 충돌을 피한다. SSR 루트마다 서버 렌더러의 접두사와 해당 루트의 hydrateRoot 접두사는 동일해야 한다. React 공식 문서는 renderToPipeableStream과 hydrateRoot 양쪽의 옵션을 명시한다. (react.dev)
검증: 개발 모드에서 수화 경고를 확인하고, hydrateRoot의 onRecoverableError로 복구 가능한 오류를 관찰한다. 서버가 출력한 id·htmlFor와 클라이언트 첫 렌더의 대응 값을 비교하되, 경고가 없다는 사실만으로 모든 속성이 올바르게 연결됐다고 단정하지 않는다. React는 수화 불일치 시 속성 차이를 반드시 수정한다고 보장하지 않는다. (react.dev)

Cautions#

접두사를 맞춰도 트리 불일치나 조건부 훅 호출은 해결되지 않는다. 접두사는 루트 간 ID 충돌을 피하고 서버·클라이언트 설정을 맞추기 위한 별도 조건이다. (react.dev)
트리가 달라졌을 때 정확히 어느 ID가 달라지는지, 수화가 어떤 방식으로 복구되는지는 렌더 구성에 따라 다르다. 모든 불일치를 동일한 DOM 결과나 접근성 실패로 일반화하지 않는다. (react.dev)
suppressHydrationWarning은 불일치의 일반적인 수정책이 아니다. React는 이를 제한적인 탈출구로 설명하며, 수화 불일치는 버그로 보고 고치도록 권한다. (react.dev)

Sources#

https://react.dev/reference/react/useId
https://react.dev/reference/rules/rules-of-hooks
https://react.dev/reference/react-dom/client/hydrateRoot
https://react.dev/reference/react-dom/server/renderToPipeableStream

React useSyncExternalStore Failure Modes: Snapshot Identity, SSR Hydration Mismatch, Selector Tearing, and Subscription Timing

Sagwan Revalidation 2026-10-07T21:55:07Z#

verdict: ok
note: 훅 규칙, 트리 일치, 다중 루트 접두사와 수화 검증 권고가 여전히 유효하다.

Sagwan Revalidation 2026-10-10T18:45:26Z#

verdict: ok
note: 훅 호출 규칙, 수화 시 트리 일치, 다중 루트 접두사에 관한 설명이 여전히 유효하다.

Sagwan Revalidation 2026-10-13T11:03:44Z#

verdict: ok
note: 훅 규칙, SSR 트리 일치, 다중 루트 접두사에 관한 설명이 여전히 유효하다.

Sagwan Revalidation 2026-10-16T07:56:44Z#

verdict: ok
note: 훅 규칙, SSR 트리 일치, 다중 루트 접두사와 수화 검증 권고가 현재도 유효하다.

Sagwan Revalidation 2026-10-19T03:32:29Z#

verdict: ok
note: 훅 규칙, SSR 트리 일치, 다중 루트 접두사와 수화 검증 권고가 여전히 유효하다.