Color Mode

라이트/다크 컬러 모드 지원을 추가하는 방법을 다루는 개념 문서예요. Chakra UI는 next-themes 라이브러리에 기반해 이를 지원해요.

출처: 문서

본문

Chakra UI는 라이트/다크 컬러 모드 지원을 추가하기 위해 next-themes에 의존해요.

설정 (Setup)

대부분의 경우 CLI가 Provider 컴포넌트에 이미 설치하고 설정해 두었을 거예요. 그렇지 않다면 수동으로 설치할 수 있어요.

npx @chakra-ui/cli snippet add color-mode

이 스니펫은 Chakra v2와 비슷하게 느껴지게 하는 훅과 컴포넌트를 포함해요.

import {
  ColorModeButton,
  DarkMode,
  LightMode,
  useColorMode,
  useColorModeValue,
} from "@/components/ui/color-mode"

`useColorMode`

useColorMode 훅은 현재 컬러 모드와 컬러 모드를 토글하는 함수를 반환해요.

앱 트리의 어디서든 toggleColorMode 또는 setColorMode를 호출하면 컬러 모드가 라이트에서 다크로(그리고 그 반대로) 전환돼요.

`useColorModeValue`

useColorModeValue 훅은 현재 컬러 모드에 따라 값을 반환해요.

다음은 시그니처예요:

const result = useColorModeValue("<light-mode-value>", "<dark-mode-value>")

반환되는 값은 컬러 모드가 light이면 라이트 모드 값, 컬러 모드가 dark이면 다크 모드 값이 돼요.

Hydration 불일치 (Hydration Mismatch)

SSR에서 useColorModeValue 또는 useColorMode를 사용하면 페이지가 마운트될 때 hydration 불일치가 발생할 수 있어요. 컬러 모드 값이 서버 쪽에서 계산되기 때문이에요.

이를 피하려면 useColorModeValue를 사용하는 컴포넌트를 ClientOnly 컴포넌트로 감싸고, 클라이언트 쪽에 마운트될 때까지 스켈레톤을 렌더링해 주세요.

ColorModeButton

컬러 모드 스니펫에는 ColorModeButton 컴포넌트가 내장돼 있어요. 이를 import하면 컬러 모드를 토글하는 아이콘 버튼을 렌더링할 수 있어요.

서버 쪽에서는 스켈레톤을, 클라이언트 쪽에서는 아이콘을 렌더링해요.

강제 컬러 모드 (Forced Color Mode)

컬러 모드 스니펫에는 LightMode와 DarkMode 컴포넌트가 내장돼 있어요. 이를 import하면 컬러 모드를 강제할 수 있어요.

LightMode와 DarkMode 컴포넌트는 최근에 스니펫에 추가되었으므로 color-mode.tsx 스니펫을 업데이트해야 할 수도 있어요.

가이드 (Guides)

기본 컬러 모드 설정

기본 컬러 모드를 설정하려면 components/ui/color-mode.tsx 파일의 ColorModeProvider를 업데이트해 주세요.

기본값을 라이트 모드로:

export function ColorModeProvider(props: ColorModeProviderProps) {
  return (
    <ThemeProvider
      attribute="class"
      disableTransitionOnChange
      defaultTheme="light"
      {...props}
    />
  )
}

기본값을 다크 모드로:

export function ColorModeProvider(props: ColorModeProviderProps) {
  return (
    <ThemeProvider
      attribute="class"
      disableTransitionOnChange
      defaultTheme="dark"
      {...props}
    />
  )
}

시스템 기본 설정 존중 (기본값):

export function ColorModeProvider(props: ColorModeProviderProps) {
  return (
    <ThemeProvider
      attribute="class"
      disableTransitionOnChange
      defaultTheme="system"
      {...props}
    />
  )
}

시스템 기본 설정 비활성화

기본적으로 컬러 모드는 사용자의 시스템 기본 설정을 존중해요. 이를 비활성화하고 light 또는 dark 모드만 사용하려면 enableSystem을 false로 설정해 주세요.

export function ColorModeProvider(props: ColorModeProviderProps) {
  return (
    <ThemeProvider
      attribute="class"
      disableTransitionOnChange
      defaultTheme="light"
      enableSystem={false}
      {...props}
    />
  )
}

커스텀 저장 키 사용

컬러 모드는 localStorage의 theme 키 아래에 저장돼요. 커스텀 키를 사용하려면 storageKey prop을 설정해 주세요.

export function ColorModeProvider(props: ColorModeProviderProps) {
  return (
    <ThemeProvider
      attribute="class"
      disableTransitionOnChange
      storageKey="my-app-color-mode"
      {...props}
    />
  )
}

특정 페이지를 라이트/다크 모드로 강제하기

특정 페이지를 특정 컬러 모드로 렌더링하려면 provider에 forcedTheme prop을 설정해 주세요.

export function ColorModeProvider(props: ColorModeProviderProps) {
  return (
    <ThemeProvider
      attribute="class"
      disableTransitionOnChange
      forcedTheme="dark"
      {...props}
    />
  )
}

대안으로 LightMode 또는 DarkMode 컴포넌트를 사용해 UI의 특정 부분을 특정 컬러 모드로 렌더링할 수 있어요.

FAQ

next-themes는 Next.js에서만 작동하나요?

아니요. 이름과 달리 next-themes는 Vite, Remix, Gatsby 등을 포함한 모든 React 프레임워크에서 작동하는 범용 라이브러리예요. 이름이 오해를 부를 수 있지만, 어디서든 잘 작동해요.

더 알아보기 (Learn more)

Chakra UI에서 컬러 모드를 다루는 더 자세한 내용은 공식 문서를 확인해 보세요.