2025.07.22Next.js

🌜 Next.js로 다크모드 구현하기 (next-themes)

next-themes 라이브러리

next-themes는 Next.js에서 다크 모드를 쉽게 구현할 수 있도록 도와주는 테마 관리 라이브러리다. 별도의 상태 관리나 복잡한 코드 없이 다크/라이트 모드 토글을 구현할 수 있으며 다음 기능을 기본으로 제공한다.

시스템 테마 자동 감지
사용자가 선택한 테마를 localStorage에 저장
테마 변경 시 UI 반영
테마 전환 애니메이션 제어

사용 방법은 간단하다. next-themes의 <ThemeProvider>를 Next.js 앱의 layout 또는 최상위 컴포넌트에서 사용하여 테마를 적용할 children을 감싸면 된다. 이후 버튼 등을 통해 테마를 토글할 수 있다.

import { ThemeProvider } from 'next-themes';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider
      attribute="data-theme"
      defaultTheme="system"
      enableSystem={true}
      disableTransitionOnChange
    >
      {children}    
    </ThemeProvider>
  );
}

ThemeProvider 컴포넌트에서 자주 사용되는 props들은 다음과 같다.

- attribute
테마 값을 HTML 태그의 어떤 속성으로 저장할지 결정한다.

attribute="class" 로 지정하면 <html class="dark"> 형태로 테마가 적용된다. Tailwind CSS 기반 프로젝트에서 주로 사용된다.

attribute="data-theme" 의 경우 <html data-theme="dark"> 형태로 적용된다. 직접 CSS를 작성하여 커스터마이징할 때 많이 사용된다.

- defaultTheme
사용자가 테마를 설정하지 않았을 때 적용할 기본 테마를 지정하는 옵션이다. 다음 3가지 값을 사용할 수 있다.

light -> 라이트 모드를 기본값으로 사용
dark -> 다크 모드를 기본값으로 사용
system -> 사용자의 OS 테마 설정을 사용

- enableSystem
defaultTheme이 system일 때 운영체제 테마를 감지할지 여부를 결정하는 옵션이다.

true -> 사용자의 OS 테마 설정을 감지하여 자동으로 테마를 변경
false -> 시스템 테마를 무시하고 수동으로 설정한 테마를 유지

- storageKey
next-themes에서 localStorage에 테마 설정을 저장할 때 사용할 키 이름을 지정하는 옵션이다. 기본값은 "theme"이며 이 값을 변경하면 브라우저 저장소에서 사용하는 키 이름을 직접 지정할 수 있다.

- disableTransitionOnChange
테마 변경 시 CSS transition을 비활성화하는 옵션이다. 테마 전환 과정에서 화면이 깜빡이거나 애니메이션 충돌이 발생하는 현상을 방지할 때 사용한다.

- themes
사용할 테마 목록을 직접 정의할 때 사용하는 옵션이다. 기본값은 ["light", "dark"] 이다.

테마 토글 컴포넌트 구현

ThemeProvider를 설정한 이후에는 useTheme() 훅을 사용하여 현재 테마 상태를 가져오고 이를 토글 할 수 있는 버튼만 추가하면 된다.

'use client';
import { useEffect, useState, useCallback } from 'react';

import { useTheme } from 'next-themes';
import { MdOutlineDarkMode, MdOutlineLightMode } from 'react-icons/md';

export function ThemeSwitcher() {
  const { resolvedTheme, setTheme } = useTheme();
  
  // * hydration mismatch 방지 (아래 문단 참고)
  const [mounted, setMounted] = useState(false);
  
  // 테마 토글 함수
  const toggle = useCallback(() => {
    setTheme(resolvedTheme === 'light' ? 'dark' : 'light');
  }, [resolvedTheme, setTheme]);
  
  // * 컴포넌트가 클라이언트에서 마운트되었는지 확인
  useEffect(() => {
    setMounted(true)
  }, []);
  
  // * 서버 렌더링 상태에서는 UI를 렌더링하지 않음
  if (!mounted) return null;
  
  return (
    <button onClick={toggle} aria-label='테마 전환 버튼'>
      {resolvedTheme === 'light'       
        ? <MdOutlineDarkMode size={24} />
        : <MdOutlineLightMode size={24} />
      }
    </button>
  );
}

useTheme() 훅에서 자주 사용하는 값은 다음과 같다.

- theme
현재 설정된 테마 상태를 의미한다. 값은 "light", "dark", "system" 중 하나이며 사용자가 직접 선택한 설정 값을 확인할 때 사용한다.

- resolvedTheme
실제 화면에 적용되는 테마 값을 의미한다. system 설정일 경우 OS 테마를 해석한 결과가 반영된다. UI 렌더링이나 아이콘 표시에는 이 값을 사용하는 것이 일반적이다.

- setTheme
테마를 변경할 때 사용하는 함수이다. 호출 시 테마 상태가 업데이트되고 UI가 즉시 반영된다.

* hydration mismatch 문제

다크 모드 기본 세팅이 이후 추가로 고려해야 할 사항이 있다. 바로 초기 렌더링 과정에서 발생할 수 있는 깜빡임 현상 즉 FOUC(Flash of Unstyled Content) 문제이다.

next-themes를 사용하여 Next.js에서 서버사이드 렌더링을 구현하면 서버는 클라이언트의 localStorage에 저장된 테마 정보를 알 수 없다.

이로 인해 사용자가 이전에 다크 모드를 설정했더라도 서버에서는 기본 테마로 HTML을 렌더링하게 된다. 이후 클라이언트에서 JavaScript가 실행되면서 저장된 테마 값을 읽고 UI를 다시 렌더링하기 때문에 화면이 한 번 깜빡이는 현상이 발생할 수 있다.

이 문제를 해결하기 위해서는 테마 정보가 준비되기 전까지 테마에 의존하는 UI를 렌더링하지 않는 방법을 사용한다. 일반적으로 useTheme() 훅과 함께 mounted 상태를 활용하여 클라이언트 마운트가 완료된 이후에만 UI를 표시하도록 처리한다.

추가로 SSR과 CSR이 일치하지 않을 경우 Hydration mismatch 경고가 발생하게 되는데 이를 숨기고 싶다면 HTML 태그 혹은 오류가 발생하는 태그에 suppressHydrationWarning 속성을 추가할 수 있다.

<html lang="ko" suppressHydrationWarning>

스타일 설정

모든 설정을 마쳤다면 마지막으로 다크 모드와 라이트 모드에서 각각 적용될 스타일을 정의해야 한다.

Tailwind CSS를 사용하는 경우 dark: 접두어를 활용하여 다크 모드 스타일을 간단하게 분기할 수 있다. 이 방식에서는 대부분의 스타일을 클래스 단위로 처리할 수 있기 때문에 별도의 테마 CSS를 작성할 필요가 거의 없다.

반면 직접 CSS를 작성하는 경우에는 next-themes의 ThemeProvider에서 설정한 attribute 값에 따라 [data-theme="dark"] 또는 .dark 셀렉터를 활용하여 테마별 스타일을 적용할 수 있다.

아래는 attribute="data-theme"을 사용했을 때의 CSS 예시이다.

/* 라이트 테마 */
:root {
  --bg-color: #F8F9FA;
  --text-color: #212529;
}

/* 다크 테마 */
html[data-theme="dark"] {
  --bg-color: #121212;
  --text-color: #E0E0E0;
}

이와 같이 CSS 변수를 활용하면 실제 스타일에서 var(--bg-color)와 같은 형태로 값을 참조할 수 있으며 현재 테마에 맞는 값이 자동으로 적용된다. 이를 통해 테마 변경 시 여러 스타일을 효율적으로 관리할 수 있다.