API reference
usePenumbra, PenumbraToggle, definePenumbraTransition, the module options and the types.
usePenumbra
Auto-imported. Returns the current theme and the functions that change it.
function usePenumbra(): Penumbra
interface Penumbra {
/** The theme that is applied now. Never 'system'. */
theme: ComputedRef<string>
/** What the visitor chose: a theme name, or 'system'. */
preference: ComputedRef<string>
/** The configured theme names, in order. */
themes: readonly string[]
setTheme: (preference: string, options?: SetThemeOptions) => void
toggleTheme: (options?: SetThemeOptions) => void
}
<script setup lang="ts">
const { theme, preference, themes, setTheme, toggleTheme } = usePenumbra()
</script>
themeis the theme on screen. Until color-mode has resolved'system'in the browser, it returns the visitor’s concrete choice, orlightas a fallback.setTheme(preference, options)switches to a theme by name, or to'system'. With a name that is not inthemes, color-mode mode hands the value to color-mode, and standalone mode ignores it.toggleTheme(options)moves to the next theme inthemesafter the current one, and wraps around. On the server it does nothing.- On the server,
setThemeonly writes the preference, because there is no page to animate.
SetThemeOptions
interface SetThemeOptions {
transition?: string // effect name, default: the module's `transition`
duration?: number // milliseconds, default: the module's `duration`
easing?: string // CSS easing, default: the module's `easing`
origin?: Origin // where a reveal starts
direction?: Direction // 'up' | 'down' | 'left' | 'right', default 'right'
}
type Origin = MouseEvent | Element | { x: number; y: number } | 'center'
Without an origin, the module uses a click from the last second, else the middle of the screen. See transitions.
PenumbraToggle
Auto-registered component. A native <button type="button"> that cycles through the themes.
| Prop | Type | Default | What it does |
|---|---|---|---|
themes |
string[] |
the module’s themes |
Themes to cycle through. |
transition |
string |
the module’s transition |
Effect name. |
duration |
number |
the module’s duration |
Milliseconds. |
easing |
string |
the module’s easing |
CSS easing. |
direction |
Direction |
'right' |
Which way directional effects travel. |
The click event is passed as the origin.
Slot
The default slot fills the button content. The default content is the current theme name, empty until mount.
defineSlots<{
default?: (props: {
theme: string // the theme on screen
next: string // the theme a click switches to
ready: boolean // false until the page is mounted
}) => unknown
}>()
<PenumbraToggle v-slot="{ theme, next, ready }">
<MoonIcon v-if="ready && theme === 'light'" />
<SunIcon v-else-if="ready" />
</PenumbraToggle>
Accessible name
aria-label is Theme: <current>. Switch to <next>. once mounted, and Switch theme before. See accessibility.
Styling
The button has the class penumbra-toggle and no other style, except a border in forced colors mode. Style it yourself.
definePenumbraTransition
Auto-imported alias of defineTransition from @penumbra/core. See custom transitions.
function definePenumbraTransition(name: string, definition: TransitionDefinition): TransitionDefinition
Module options
Set them under penumbra in nuxt.config.ts.
export default defineNuxtConfig({
penumbra: {
mode: 'color-mode',
themes: ['light', 'dark'],
transition: 'circle',
duration: 500,
easing: 'ease-in-out',
},
})
| Option | Type | Default | Mode |
|---|---|---|---|
mode |
'color-mode' | 'standalone' |
'color-mode' if @nuxtjs/color-mode is installed, else 'standalone' |
both |
themes |
string[] |
['light', 'dark'] |
both |
transition |
string |
'circle' |
both |
duration |
number (ms) |
500 |
both |
easing |
string |
'ease-in-out' |
both |
default |
string |
'system' |
standalone |
attribute |
'class' | 'data-*' |
'data-theme' |
standalone |
storageKey |
string |
'penumbra-theme' |
standalone |
Details:
mode: 'color-mode'without@nuxtjs/color-modeinmodulesthrows at build time.themesis the ordertoggleThemecycles through. Names use letters, digits and dashes and start with a letter.'system'is reserved. Duplicates and an empty list throw.transitionis not checked against the registry. An unknown name switches instantly.durationmust be 0 or more.0disables the animation.- Standalone options are described in standalone mode.
Types
The package entry exports the option and API types:
import type {
Direction,
ModuleOptions,
Origin,
Penumbra,
ResolvedOptions,
SetThemeOptions,
TransitionContext,
TransitionDefinition,
} from 'nuxt-penumbra'
ResolvedOptions is Required<ModuleOptions>, the shape of runtimeConfig.public.penumbra.
The $penumbra plugin
The client plugin provides $penumbra with setTheme, toggleTheme, intercept and themes. Use usePenumbra() instead; $penumbra is an internal detail and intercept is not meant to be called.