Theme ModeSSR-safe theme state for Nuxt and Vue

A Nuxt color mode module, Vue toggle primitives, and framework-neutral helpers that keep selected mode and resolved theme separate.

Install package

Nuxt-first SSR

Writes data-theme, data-theme-mode, color-scheme, and icon CSS variables before Vue mounts.

Renderless Vue toggle

Exposes mode, resolvedTheme, nextMode, label, and actions while your app owns the markup.

Core helpers

Parse options, persist mode, resolve preference, and update DOM attributes from plain TypeScript.

Stored mode stays explicit: auto remains auto, while the resolved theme follows the OS.Import only the Nuxt, Vue, or core entry point your app actually uses.

Install from GitHub Packages

One flow: register GitHub Packages, install the package, then import only the entry point your app actually uses.

Add the GitHub Packages registry to .npmrc:

.npmrc

ini

@alyldas:registry=https://npm.pkg.github.com

Package reads can require a token with read:packages.

Install the package:

terminal

npm install @alyldas/theme-mode

Import the CSS and your entry point:

theme-mode.ts

import '@alyldas/theme-mode/style.css'
import '@alyldas/theme-mode/nuxt'

Choose an entry point

Replace the entry-point import above with one of these lines:

@alyldas/theme-mode/nuxt

Nuxt module

Best for Nuxt apps that need theme state before hydration.

Adds the SSR-safe bootstrap path and keeps runtime options aligned.

import '@alyldas/theme-mode/nuxt'

@alyldas/theme-mode/vue

Vue composable and toggle

Best for app shells, custom buttons, widgets, and tests.

Use the shared controller or the renderless toggle slot in your own UI.

import '@alyldas/theme-mode/vue'

@alyldas/theme-mode/core

Framework-neutral helpers

Best for adapters that only need parsing, persistence, and DOM writes.

Use it from plain TypeScript when no Vue runtime is involved.

import '@alyldas/theme-mode/core'

Nuxt setup

Start with the module only. Add options when you need custom storage keys, attributes, or CSS variable prefixes.

minimal setupextended options

export default defineNuxtConfig({
  modules: ['@alyldas/theme-mode/nuxt'],
})

export default defineNuxtConfig({
  modules: ['@alyldas/theme-mode/nuxt'],
  themeMode: {
    // Before Vue mounts
    defaultMode: 'auto',
    fallbackTheme: 'dark', // color-scheme: native controls
    attribute: 'data-theme', // data-theme: light | dark
    modeAttribute: 'data-theme-mode', // data-theme-mode: auto | dark | light
    cssVariablePrefix: 'theme-mode', // --theme-mode-*: toggle state
    storageKey: 'theme',
  },
})