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