Migration Guide

Migrating to v4

v4 of @nuxtjs/color-mode requires Nuxt 3+ and drops support for Nuxt Bridge. It also introduces several breaking changes to improve the module.

Main Changes

1. No Default Class Suffix

The default classSuffix has been removed. If you were relying on the default -mode suffix, you'll need to explicitly set it in your configuration:

export default defineNuxtConfig({
  colorMode: {
    classSuffix: '-mode'
  }
})

Or update your CSS classes to remove the suffix:

- .dark-mode { }
- .light-mode { }
+ .dark { }
+ .light { }

2. CommonJS Support Dropped

The module no longer provides CommonJS builds. Ensure your project is using ESM (which is the default for Nuxt 3).

3. Read-Only Color Mode Value

You can no longer directly set colorMode.value. Use colorMode.preference instead:

<script setup>
const colorMode = useColorMode()

- colorMode.value = 'dark'
+ colorMode.preference = 'dark'
</script>

The value property is now read-only and reflects the actual color mode being used (which may differ from preference when using system preference detection).

4. Removed hid Option

The defunct hid configuration option has been removed. If you were using it in your config, simply remove it:

export default defineNuxtConfig({
  colorMode: {
-   hid: 'nuxt-color-mode-script',
    preference: 'system',
  }
})

5. Nuxt Bridge Support Dropped

Support for Nuxt Bridge has been removed. If you're still using Nuxt Bridge, you should continue using v3. Otherwise, upgrade to Nuxt 3+.

Migrating to v3

v3 of @nuxtjs/color-mode requires either Nuxt Bridge or Nuxt 3+. If you are using Nuxt 2 without Bridge, you should continue to use v2.

Main Changes

1. Page Meta Configuration

The main change between Nuxt 2 → Nuxt 3+ is that you will define your color mode at the page level with definePageMeta:

<template>
  <h1>This page is forced with light mode</h1>
</template>

- <script>
- export default {
-   colorMode: 'light',
- }
+ <script setup>
+ definePageMeta({
+   colorMode: 'light',
+ })
</script>

2. Composable API

The $colorMode helper remains the same, but there is also a new composable (useColorMode) which is the recommended way of accessing color mode information.

<script setup>
const colorMode = useColorMode()

// Access properties
console.log(colorMode.preference)
console.log(colorMode.value)
</script>

3. Type Imports

If you were directly importing color mode configuration types, note that this has been renamed to ModuleOptions.

// Before
import type { ColorModeConfig } from '@nuxtjs/color-mode'

// After
import type { ModuleOptions } from '@nuxtjs/color-mode'