InitColorSchemeScript

InitColorSchemeScript 컴포넌트는 서버 사이드 렌더링 애플리케이션에서 다크 모드 깜빡임(flickering)을 제거해요.

출처: 문서

본문

소개 (Introduction)

InitColorSchemeScript 컴포넌트는 서버 사이드 렌더링(SSR) 애플리케이션에서 발생할 수 있는 다크 모드 깜빡임을 제거하는 데 사용돼요. 이 스크립트는 React보다 먼저 실행되어 사용자 선호도에 기반한 속성을 부착해, 첫 렌더링에서 올바른 컬러 모드가 적용되도록 해요.

최상의 사용자 경험을 위해, 라이트와 다크 모드를 모두 지원하는 서버 렌더링 Material UI 앱이라면 이 컴포넌트를 구현해야 해요.

기본 (Basics)

먼저 테마에서 colorSchemeSelector: 'data'로 CSS 변수를 활성화해요.

import { ThemeProvider, createTheme } from '@mui/material/styles';

const theme = createTheme({
  cssVariables: {
    colorSchemeSelector: 'data',
  },
});

function App() {
  return <ThemeProvider theme={theme}>{/* Your app */}</ThemeProvider>;
}

그런 다음, InitColorSchemeScript 컴포넌트를 <body> 태그의 첫 번째 자식으로 렌더링해요.

아래 섹션들은 Next.js로 작업할 때 InitColorSchemeScript 컴포넌트를 어디에 렌더링해야 하는지 자세히 설명해요.

Next.js App Router

루트 layout 파일에 InitColorSchemeScript 컴포넌트를 배치해요:

import InitColorSchemeScript from '@mui/material/InitColorSchemeScript';

export default function RootLayout(props: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <InitColorSchemeScript attribute="data" />
        {props.children}
      </body>
    </html>
  );
}

Next.js Pages Router

커스텀 _document 파일에 InitColorSchemeScript 컴포넌트를 배치해요:

import { Html, Head, Main, NextScript } from 'next/document';
import InitColorSchemeScript from '@mui/material/InitColorSchemeScript';

export default function MyDocument(props) {
  return (
    <Html lang="en">
      <Head>{/* tags */}</Head>
      <body>
        <InitColorSchemeScript attribute="data" />
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

커스터마이즈 (Customization)

클래스 속성 (Class attribute)

DOM 요소에 클래스를 부착하려면 attribute prop을 "class"로 설정해요.

<InitColorSchemeScript attribute="class" />

이것은 사용자의 시스템 선호도에 따라 컬러 스킴 노드(기본값은 <html>)에 클래스 이름을 설정해요.

<html class="dark"></html>

임의의 속성 (Arbitrary attribute)

DOM 요소에 임의의 속성을 부착하려면 attribute prop에서 %s를 플레이스홀더로 사용해요.

<InitColorSchemeScript attribute="[data-theme='%s']" /> // <html data-theme="dark">
<InitColorSchemeScript attribute=".mode-%s" /> // <html class="mode-dark">

기본 모드 (Default mode)

defaultMode prop을 설정해서 사용자가 페이지를 처음 방문할 때의 기본 모드를 지정해요.

예를 들어 사용자가 첫 방문에서 다크 모드를 보게 하려면 defaultMode prop을 "dark"로 설정해요.

<InitColorSchemeScript defaultMode="dark" />

주의사항 (Caveats)

속성 (Attribute)

attribute prop을 커스터마이즈할 때는 테마의 colorSchemeSelector도 사용 중인 속성에 맞게 설정해야 해요.

const theme = createTheme({
  cssVariables: {
    colorSchemeSelector: 'same value as the `attribute` prop',
  },
});

기본 모드 (Default mode)

defaultMode prop을 커스터마이즈할 때는 ThemeProvider 컴포넌트에서도 동일하게 설정해야 해요:

<ThemeProvider theme={theme} defaultMode="dark">