Nuxt3 다크모드 적용하기

@nuxtjs/color-mode로 Nuxt 3에 다크 모드를 적용하는 방법. 설정, useColorMode()와 $colorMode의 차이, 토글 버튼과 초기 테마 설정까지 정리했다.

Nuxt3에서 다크모드를 적용하고 관리하는 방법을 알아보자.

업데이트 (2026.10.16): 처음 쓴 내용 중 틀린 부분 세 곳을 고쳤다. 시스템 설정 자동 적용 예제(colorMode.value === 'system'은 참이 될 수 없음), 서버 렌더링에서 아이콘이 어긋나는 문제, 다크 모드 CSS 클래스 이름(.dark인지 .dark-mode인지)이다. 고친 곳마다 표시해 뒀다.

필요한 모듈 설치

Nuxt3에서 다크모드를 사용하려면 @nuxtjs/color-mode 모듈을 설치해야 한다.

npx nuxi module add color-mode

nuxt.config.ts 설정

설치가 끝났으면 nuxt.config.ts 파일에서 모듈을 추가해야 한다.

export default defineNuxtConfig({
  modules: [
    '@nuxtjs/color-mode'
  ]
})

useColorMode()와 $colorMode 차이점

Nuxt에서 컬러 모드를 다룰 때는 useColorMode()와 $colorMode 두 가지 방법이 있다.

1. $colorMode

  • 템플릿(HTML)에서 바로 접근 가능
  • $colorMode.value를 사용해서 현재 컬러 모드를 가져올 수 있음
  • preference 값을 변경하면 컬러 모드가 바뀜

템플릿에서 다크모드 버튼을 만들 때 $colorMode.value를 활용할 수 있다.

<template>
  <button @click="$colorMode.preference = $colorMode.value === 'light' ? 'dark' : 'light'">
    <span v-if="$colorMode.value === 'light'">라이트 모드</span>
    <span v-else>다크 모드</span>
  </button>
</template>

2. useColorMode()

  • setup() 함수에서 접근할 때 사용
  • const colorMode = useColorMode()로 가져와야 함
  • colorMode.preference를 변경하면 컬러 모드가 바뀜

컴포넌트 내부에서 컬러 모드를 제어할 때 사용한다.

<script setup>
const colorMode = useColorMode();

const toggleColorMode = () => {
  colorMode.preference = colorMode.value === 'light' ? 'dark' : 'light';
};
</script>

useColorMode()를 직접 불러와서 사용하는 이유

$colorMode는 템플릿 안에서만 사용할 수 있기 때문에, 스크립트(setup 함수)에서 다루려면 useColorMode()를 사용해야 한다.

고친 부분: 처음에는 여기에 "OS가 다크 모드면 자동으로 다크 모드를 적용하는" 코드를 적었는데, 동작하지 않는 코드였다.

<script setup>
const colorMode = useColorMode();

// ❌ 동작하지 않는다
if (colorMode.value === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches) {
  colorMode.preference = 'dark';
}
</script>
문제이유
colorMode.value === 'system'은 항상 거짓value는 실제로 적용된 모드(light/dark)다. 'system'이 들어가는 건 사용자가 고른 값인 preference 쪽이다
window에서 에러<script setup>은 서버에서도 실행되는데, 서버에는 window가 없다
애초에 필요 없는 코드preference의 기본값이 'system'이라, 모듈이 이미 OS 설정을 따라간다

OS 설정을 따라가게 하려면 아무것도 안 해도 된다. 사용자가 다시 "시스템 설정 따르기"를 고르게 하고 싶을 때만 preference를 'system'으로 돌려놓으면 된다.

colorMode.preference = 'system'; // 다시 OS 설정을 따라간다

다크모드 토글 버튼 예제

위 내용을 바탕으로, 다크모드 토글 기능을 구현해보자.

<template>
  <header class="header">
    <div class="header__container">
      <pre>{{ $colorMode }}</pre>

      <!-- 우측 액션 영역 (검색, 테마 전환 등) -->
      <div class="header__actions">
        <!-- 테마 전환 버튼 -->
        <button class="header__theme-btn" @click="toggleColorMode">
          <span v-if="$colorMode.value === 'light'">라이트</span>
          <span v-else>다크</span>
        </button>
      </div>
    </div>
  </header>
</template>

<script setup>
const colorMode = useColorMode(); // Nuxt 제공 훅

const toggleColorMode = () => {
  colorMode.preference = colorMode.value === 'light' ? 'dark' : 'light';
};
</script>

고친 부분: 서버 렌더링에서는 아이콘을 <ClientOnly>로 감싸야 한다. 서버는 사용자의 모드를 모르기 때문에, 서버가 그린 아이콘과 브라우저가 그린 아이콘이 달라질 수 있다(하이드레이션 불일치). 이 블로그의 헤더는 이렇게 쓴다.

<button type="button" @click="toggleColorMode">
  <ClientOnly>
    <IconDark v-if="colorMode.value === 'light'" />
    <IconLight v-else />
    <template #fallback>
      <span class="placeholder" />  <!-- 같은 크기의 빈 자리. 버튼 크기가 흔들리지 않게 -->
    </template>
  </ClientOnly>
</button>

다크모드 초기 설정

기본적으로 Nuxt는 시스템 설정을 따라가지만, 특정 모드를 기본값으로 설정하고 싶다면 nuxt.config.ts에서 colorMode 옵션을 설정하면 된다.

export default defineNuxtConfig({
  modules: ['@nuxtjs/color-mode'],
  colorMode: {
    preference: 'dark', // 기본 다크모드 설정
    fallback: 'light', // 감지할 수 없을 때 사용할 기본 모드
    classSuffix: '',
  }
})

이렇게 하면 웹사이트에 처음 접속했을 때 다크모드가 적용된다.

다크모드 스타일 적용

Nuxt에서는 컬러 모드에 따라 <html> 태그에 자동으로 클래스가 추가된다. 클래스 이름은 classSuffix 설정에 따라 다르다.

설정다크 모드일 때 클래스
기본값 (classSuffix를 안 씀).dark-mode
classSuffix: '' (위 예제).dark

고친 부분: 처음에는 설명 없이 .dark만 적었다. 이 블로그는 classSuffix를 쓰지 않아서 실제 클래스가 .dark-mode였고, 그 결과 .dark로 적어 둔 일부 스타일이 한동안 적용되지 않고 있었다. 내 설정에서 어떤 클래스가 붙는지 개발자 도구로 <html>을 먼저 확인하자.

/* 라이트 모드 스타일 */
body {
  background-color: white;
  color: black;
}

/* 다크 모드 스타일: classSuffix: '' 이면 .dark, 기본값이면 .dark-mode */
.dark body {
  background-color: black;
  color: white;
}

Tailwind를 같이 쓴다면 Tailwind도 같은 클래스를 보게 해야 한다. 이 블로그는 기본값을 써서 이렇게 맞췄다.

// tailwind.config.js
export default {
  darkMode: ["selector", ".dark-mode"],
};

이제 다크모드를 적용한 Nuxt3 프로젝트를 만들 수 있다.

📌 공식 문서 참고: https://nuxt.com/modules/color-mode