Skip to content
nuxt-penumbra
Esc
↑↓navigate↵open⌘Jpreview
On this page

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-mode
pnpm add nuxt-penumbra @nuxtjs/color-mode
yarn add nuxt-penumbra @nuxtjs/color-mode
bun add nuxt-penumbra @nuxtjs/color-mode
nub add nuxt-penumbra @nuxtjs/color-mode
aube add nuxt-penumbra @nuxtjs/color-mode

The 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

Was this page helpful?