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

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>
  • theme is the theme on screen. Until color-mode has resolved 'system' in the browser, it returns the visitor’s concrete choice, or light as a fallback.
  • setTheme(preference, options) switches to a theme by name, or to 'system'. With a name that is not in themes, color-mode mode hands the value to color-mode, and standalone mode ignores it.
  • toggleTheme(options) moves to the next theme in themes after the current one, and wraps around. On the server it does nothing.
  • On the server, setTheme only 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-mode in modules throws at build time.
  • themes is the order toggleTheme cycles through. Names use letters, digits and dashes and start with a letter. 'system' is reserved. Duplicates and an empty list throw.
  • transition is not checked against the registry. An unknown name switches instantly.
  • duration must be 0 or more. 0 disables 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.

Was this page helpful?