Getting started
Install nuxt-penumbra next to @nuxtjs/color-mode, write the theme CSS and switch themes from a button.
This page uses @nuxtjs/color-mode, which is the usual choice. Without it, see standalone mode. With Nuxt UI, see Nuxt UI.
Install
npm install nuxt-penumbra @nuxtjs/color-modepnpm add nuxt-penumbra @nuxtjs/color-modeyarn add nuxt-penumbra @nuxtjs/color-modebun add nuxt-penumbra @nuxtjs/color-modenub add nuxt-penumbra @nuxtjs/color-modeaube add nuxt-penumbra @nuxtjs/color-modeThe module was written against Nuxt 4. Its nuxt compatibility field is >=3.12.0, but Nuxt 3 has not been run. See browser support and compatibility.
@nuxtjs/color-mode is an optional peer dependency (^3.0.0 || ^4.0.0). Install it when you want color-mode mode.
Add the modules
export default defineNuxtConfig({
modules: ['@nuxtjs/color-mode', 'nuxt-penumbra'],
colorMode: { classSuffix: '' },
penumbra: { transition: 'circle', duration: 500 },
})
With @nuxtjs/color-mode present, the module runs in color-mode mode. It never stores a theme itself. Color-mode keeps storing the preference in its cookie or localStorage, and nuxt-penumbra animates the changes to useColorMode().preference.
classSuffix: '' makes color-mode add dark instead of dark-mode to <html>. That is a color-mode option, not a nuxt-penumbra one, and the CSS below assumes it. Every penumbra option is listed in the API reference.
The module sets itself up after all other modules (modules:done), so the order of the modules array does not matter.
Write the theme CSS
nuxt-penumbra ships no palette. Color-mode puts a class on <html>, and you select on it:
:root {
color-scheme: light;
--bg: #fff;
--fg: #111;
}
:root.dark {
color-scheme: dark;
--bg: #000;
--fg: #eee;
}
body {
background: var(--bg);
color: var(--fg);
}
export default defineNuxtConfig({
css: ['~/assets/css/main.css'],
})
Color-mode’s inline head script sets the class before first paint, which is why a reload does not flash. See SSR and storage.
Switch the theme
PenumbraToggle is a button that cycles through themes. It passes the click as the origin, so the reveal starts where the visitor clicked.
<template>
<PenumbraToggle />
</template>
To build your own button, use the composable:
<script setup lang="ts">
const { theme, toggleTheme } = usePenumbra()
function onClick(event: MouseEvent) {
toggleTheme({ origin: event })
}
</script>
<template>
<button type="button" @click="onClick">Theme: {{ theme }}</button>
</template>
To pick a theme by name, or to go back to following the system, call setTheme:
const { setTheme } = usePenumbra()
setTheme('dark', { transition: 'wipe', direction: 'down' })
setTheme('system') // needs the themes "light" and "dark"
Writing useColorMode().preference directly also animates. That is how Nuxt UI’s color mode components work, and it is covered in Nuxt UI.
Next
- Transitions: the built-in effects and how to tune them.
- Accessibility: what the button announces.
- API reference:
usePenumbra,PenumbraToggleand the module options.