Standalone mode
Use nuxt-penumbra without @nuxtjs/color-mode, with its own store, localStorage persistence and a no-flash head script.
Standalone mode is for sites that do not use @nuxtjs/color-mode. The module keeps its own small theme store, saves the visitor’s choice in localStorage, follows prefers-color-scheme, and injects a script into <head> that applies the theme before first paint.
It is the default when @nuxtjs/color-mode is not in modules. You can also force it with mode: 'standalone'.
export default defineNuxtConfig({
modules: ['nuxt-penumbra'],
penumbra: {
themes: ['light', 'dark', 'sepia'],
default: 'system',
attribute: 'data-theme',
storageKey: 'penumbra-theme',
},
})
What the store does
- The visitor’s choice (a theme name or
'system') is saved inlocalStorageunderstorageKey. If storage is blocked or full, the choice still applies to the current page. 'system'followsprefers-color-schemeand updates live when the system setting changes. It needs the themeslightanddarkinthemes.- A change in another tab is picked up through the
storageevent, so open tabs stay in step. - The store starts after hydration (
app:mounted), so the stored choice does not clash with the server-rendered markup.
The head script
The module adds an inline script to <head> with the highest priority, so it runs before the stylesheet is applied and before first paint. It reads the same storage key, resolves 'system', and sets the attribute or class on <html>. It also listens for system and cross-tab changes, so the page stays correct before Vue has hydrated.
The script is built from your options and contains the theme names, default, attribute and storageKey. If your site uses a strict Content-Security-Policy, an inline script needs a hash or a nonce. That has not been tested here.
Options
| Option | Default | What it does |
|---|---|---|
default |
'system' |
The theme before the visitor picks one. A theme name, or 'system'. |
attribute |
'data-theme' |
What the module sets on <html>: 'class' toggles a class, 'data-*' sets a value. |
storageKey |
'penumbra-theme' |
The localStorage key that holds the choice. |
themes, transition, duration and easing apply in both modes. The module throws at build time for a default that is not in themes, for default: 'system' without light and dark, and for an empty storageKey.
Write the CSS
With the default attribute, select on data-theme:
:root {
color-scheme: light;
--bg: #fff;
--fg: #111;
}
:root[data-theme='dark'] {
color-scheme: dark;
--bg: #000;
--fg: #eee;
}
:root[data-theme='sepia'] {
color-scheme: light;
--bg: #f4ecd8;
--fg: #3b2f1e;
}
body {
background: var(--bg);
color: var(--fg);
}
With attribute: 'class' the module toggles a class named after the theme and removes the others, so select on :root.dark instead.
Use it
<template>
<PenumbraToggle />
</template>
const { theme, preference, setTheme } = usePenumbra()
setTheme('sepia')
setTheme('system')
theme is the theme on screen and is never 'system'. preference is what the visitor chose and can be 'system'.
Server rendering
On the server the store holds the default. When default is 'system', the server renders the light theme state. The head script then fixes the page before paint, and the store adopts the real value after hydration. Text that depends on the theme can therefore differ between server and client; PenumbraToggle waits for mount before it shows its live label. See SSR and storage.