Client Only

클라이언트 쪽에서만 콘텐츠를 렌더링할 때 사용하는 컴포넌트예요. SSR 환경에서 브라우저 전용 API를 안전하게 다룰 때 특히 유용해요.

출처: 문서

본문

사용법 (Usage)

import { ClientOnly, Skeleton } from "@chakra-ui/react"

<ClientOnly>
  <ColorModeButton />
</ClientOnly>

예시 (Examples)

Fallback (대체 콘텐츠)

fallback prop을 사용하면 클라이언트 콘텐츠가 준비되는 동안 로딩 상태를 렌더링할 수 있어요.

Render Prop (권장)

컴포넌트가 브라우저 전용 API(window, document, localStorage 등)에 접근한다면 render prop 패턴을 사용해 서버 사이드 렌더링 문제를 방지할 수 있어요.

이 패턴은 브라우저 API에 접근하는 컴포넌트가 오직 클라이언트 쪽에서만 평가되도록 보장해서, hydration 불일치(hydration mismatch)와 서버 사이드 오류를 막아줘요.

서버 쪽에는 필요 없는 무거운 컴포넌트를 렌더링할 때도 사용할 수 있어요.

Direct Children (주의해서 사용)

컴포넌트를 children으로 직접 전달할 수도 있지만, 브라우저 API에 접근하는 컴포넌트는 주의해야 해요:

/* ❌ This may cause server-side errors */
<ClientOnly fallback={<Skeleton />}>
  <ComponentThatUsesWindow />
</ClientOnly>

/* ✅ This is safe */
<ClientOnly fallback={<Skeleton />}>
  {() => <ComponentThatUsesWindow />}
</ClientOnly>

Props

이러한 prop들을 ClientOnly 컴포넌트에 전달할 수 있어요.

더 알아보기 (Learn more)

Chakra UI의 ClientOnly 컴포넌트에 대해 더 자세히 알아보려면 공식 문서를 확인해 보세요.