repository·main·Indexed 22 days ago
https://github.com/nuxt-modules/color-modeA Nuxt module for implementing dark and light modes with automatic system preference detection. It manages color preferences by applying configurable CSS classes (e.g., .dark or .light) to the <html> element and provides the useColorMode() composable and $colorMode global property for state management. Compatible with Nuxt 3+, it supports client-side and universal rendering, page-level mode forcing via definePageMeta, and integration with Tailwind CSS v3 and v4.
.dark or .light) to the <html> element.Nuxt Color Mode provides the following capabilities:
.${color} class (e.g., .dark or .light) to the <html> element, allowing you to write theme-specific CSS easily.color-mode preference using CSS media queries.By default, this module adds a class (e.g., .dark) to the <html> element. In Tailwind CSS v4, you must override the dark variant to use this class instead of the default prefers-color-scheme media query.
To enable dark mode support, add the following to your CSS file:
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));You can also create custom variants for other color modes (like sepia) using the same pattern:
@custom-variant sepia (&:where(.sepia, .sepia *));Then use them in your templates:
<div class="bg-white dark:bg-gray-900 sepia:bg-amber-50">
<h1 class="text-gray-900 dark:text-white sepia:text-amber-900">
Hello world
</h1>
</div>@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
@custom-variant sepia (&:where(.sepia, .sepia *));You can configure the @nuxtjs/color-mode module by providing the colorMode property in your nuxt.config.ts.
Default configuration example:
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: '/' }
}
})When moving from Nuxt 2 to Nuxt 3+, the primary change is how color mode is configured at the page level. Instead of using the component option, use definePageMeta within <script setup>.
<script setup>
definePageMeta({
colorMode: 'light',
})
</script>
<template>
<h1>This page is forced with light mode</h1>
</template>The cookieAttrs option is exposed through Nuxt's public runtime config, allowing you to change cookie attributes (like domain) per deployment without rebuilding.
Values provided via runtimeConfig or environment variables are deep-merged with your existing cookieAttrs configuration.
Important: Because storage is fixed at build time, you must set storage: 'cookie' in your nuxt.config.ts for runtime cookie overrides to work.
// Option 1: Using runtimeConfig in nuxt.config.ts
export default defineNuxtConfig({
colorMode: {
storage: 'cookie', // Must be set at build time
},
runtimeConfig: {
public: {
colorMode: {
cookieAttrs: { domain: 'example.com' }, // Merged with defaults
},
},
},
})You can override cookieAttrs using NUXT_PUBLIC_* environment variables.
Note: Environment variables can only override keys that already exist on the object. You must first declare the key (even with an empty value) in your nuxt.config.ts or runtimeConfig so the module knows it exists.
// nuxt.config.ts
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.mjsYou can override the global color mode for a specific page by using the definePageMeta macro. This is useful for incrementally implementing dark mode by forcing specific pages to remain in light mode.
When a mode is forced, the color mode picker will not be able to change the current page's mode. You can check if the current mode is being forced by inspecting the $colorMode.forced value. It is recommended to hide or disable your color mode switcher on pages where a mode is forced to avoid user confusion.
<template>
<h1>This page is forced with light mode</h1>
</template>
<script setup>
definePageMeta({
colorMode: 'light',
})
</script>Follow these steps to contribute code:
pnpm test.To use the color mode classes with Tailwind CSS v3, you must configure the darkMode option in your tailwind.config.js.
Set darkMode to 'selector' (for Tailwind v3.4.1+) or 'class'.
Note: If you are using @nuxtjs/tailwindcss v6 with Tailwind CSS v3, this configuration is handled automatically.
export default {
darkMode: 'selector',
}