Configuration
You can configure the module by providing the colorMode property in your nuxt.config.ts. Here are the default options:
export default defineNuxtConfig({
modules: ['@nuxtjs/color-mode'],
colorMode: {
preference: 'system', // default value of $colorMode.preference
fallback: 'light', // fallback value if not system preference found
globalName: '__NUXT_COLOR_MODE__',
componentName: 'ColorScheme',
classPrefix: '',
classSuffix: '',
storage: 'localStorage', // or 'sessionStorage' or 'cookie'
storageKey: 'nuxt-color-mode',
cookieAttrs: { maxAge: 31536000, path: '/' }
}
})
Options
preference
- Type:
string - Default:
'system'
Default color mode preference. 'system' is a special value that will automatically detect the color mode based on the system preferences.
fallback
- Type:
string - Default:
'light'
Fallback color mode value if no system preference is detected.
dataValue
- Type:
string - Default:
undefined
Optional dataset attribute to add to <html>. For example, if you set dataValue: 'theme', it will set data-theme="dark" on <html>. This is useful when using libraries like daisyUI.
storage
- Type:
'localStorage' | 'sessionStorage' | 'cookie' - Default:
'localStorage'
Storage type to persist the color mode preference.
storageKey
- Type:
string - Default:
'nuxt-color-mode'
Storage key name.
cookieAttrs
- Type:
object - Default:
{ maxAge: 31536000, path: '/' }
Attributes to set on the cookie when storage is set to 'cookie'. By default, the cookie is set with a one-year max age and scoped to the root path.
You can override these to customise cookie behaviour, for example to set SameSite or Secure:
export default defineNuxtConfig({
modules: ['@nuxtjs/color-mode'],
colorMode: {
storage: 'cookie',
cookieAttrs: {
maxAge: 31536000,
path: '/',
sameSite: 'lax',
secure: true,
}
}
})
Overriding cookieAttrs at runtime
cookieAttrs is the only option exposed through Nuxt's public runtime config; every other option (including storage) is baked in at build time. This means you can change the cookie attributes — most usefully the domain — per deployment without rebuilding, for example to serve one build from several hosts.
You can override it in two ways. In both cases, your value is deep-merged on top of the module's cookieAttrs default (or the one you set via colorMode.cookieAttrs), so you only need to specify the attribute you want to change — you don't need to repeat maxAge, path, etc.
In nuxt.config via runtimeConfig:
export default defineNuxtConfig({
colorMode: {
storage: 'cookie', // `storage` is build-time only, so it must be set here
},
runtimeConfig: {
public: {
colorMode: {
cookieAttrs: { domain: 'example.com' }, // merged with { maxAge: 31536000, path: '/' }
},
},
},
})
With an environment variable. NUXT_PUBLIC_* overrides only apply to keys that already exist on the object at startup — they cannot add new keys. So declare the attribute first (either via colorMode.cookieAttrs or runtimeConfig.public.colorMode.cookieAttrs) so the key exists, then override it at runtime:
colorMode: {
storage: 'cookie',
cookieAttrs: { domain: '' }, // declare `domain` so it can be overridden
}
NUXT_PUBLIC_COLOR_MODE_COOKIE_ATTRS_DOMAIN=example.com node .output/server/index.mjs
Because storage is fixed at build time, cookie storage must be enabled through the colorMode.storage option — setting storage inside runtimeConfig has no effect.