Skip to main content

ModeWatcher

API Reference for the ModeWatcher component.

Usage

Add the ModeWatcher component to your root +layout.svelte file to automatically apply mode and theme preferences:

src/routes/+layout.svelte
		<script lang="ts">
	import { ModeWatcher } from "mode-watcher";
	let { children } = $props();
</script>
 
<ModeWatcher />
{@render children()}

ModeWatcher will:

  • Detect user mode preferences (light, dark, or system)
  • Apply the appropriate class (dark by default) to the <html> element
  • Set the color-scheme attribute accordingly
  • Optionally apply a theme via the data-theme attribute

Features

Disable Tracking

ModeWatcher will automatically track operating system preferences and apply these if no user preference is set. If you wish to disable this behavior, set the track prop to false:

		<ModeWatcher track={false} />

Default Mode

Use the defaultMode prop to specify a fallback when no user preference is available:

		<ModeWatcher defaultMode="dark" />

Themes

In addition to the dark, light, and system modes, ModeWatcher can also be configured with a theme which will be applied to the root html element like so:

		<html data-theme="your-custom-theme"></html>

Theme Colors

Manage the browser's <meta name="theme-color"> dynamically based on mode:

		<ModeWatcher themeColors={{ dark: "#000", light: "#fff" }} />

Custom Class Names

Customize the class names added to <html> when switching modes:

		<ModeWatcher darkClassNames={["dddd"]} lightClassNames={["fff"]} />

Now, when the mode is dark, the root html element will have the dddd class, and when the mode is light, the root html element will have the fff class.

Custom Local Storage Keys

Override the default localStorage keys:

		<ModeWatcher modeStorageKey="my-mode-key" themeStorageKey="my-theme-key" />

CSP Nonce Support

Provide a nonce if using a strict Content Security Policy.

This will be applied to the injected <script> tag used for pre-hydration mode setting:

		<ModeWatcher nonce="my-secure-nonce" />

Disable Script Injection

Prevent ModeWatcher from injecting the initial head script by setting:

		<ModeWatcher disableHeadScriptInjection={true} />

Props

The ModeWatcher component accepts the following props:

track
type: boolean
Whether to automatically track operating system preferences and update the mode accordingly.
default: true
defaultMode
type: 'system' | 'light' | 'dark'
The default mode to use instead of the user's preference.
default: 'system'
defaultTheme
type: string

The default theme to use, which will be applied to the root html element and can be managed with the setTheme function.

themeColors
type: ThemeColors
The theme colors to use for each mode.
disableTransitions
type: boolean
Whether to disable transitions when updating the mode.
default: false
darkClassNames
type: string[]

The classes to add to the root html element when the mode is 'dark'.

default: ['dark']
lightClassNames
type: string[]

The classes to add to the root html element when the mode is 'light'.

default: []
modeStorageKey
type: string
Optionally provide a custom local storage key to use for storing the mode.
default: 'mode-watcher-mode'
themeStorageKey
type: string
Optionally provide a custom local storage key to use for storing the theme.
default: 'mode-watcher-theme'
nonce
type: string
An optional nonce to use for the injected script tag to allow-list mode-watcher if you are using a Content Security Policy.
disableHeadScriptInjection
type: boolean
Whether to disable the injected script tag that sets the initial mode. Set this if you are manually injecting the script using a hook.
default: false