repository·main·Indexed 20 days ago
https://github.com/svecosystem/mode-watcherA utility library for SvelteKit applications to manage light and dark modes. It provides automatic OS preference detection, persistence via localStorage, and theme color management. Key features include the ModeWatcher component for root layout integration, functions like toggleMode, setMode, and resetMode, and readable stores for tracking resolved mode, user preferences, and system settings without causing a flash of unstyled content (FOUC).
Mode Watcher provides two stores for tracking different preference layers:
userPrefersMode: A writable store representing the user's chosen mode preference. It accepts "light", "dark", or "system".systemPrefersMode: A readable store representing the operating system's mode preference. It returns "light", "dark", or undefined (on the server). It tracks OS changes unless track={false} is passed to the ModeWatcher component.When managing themes, it is important to distinguish between the resolved mode and the user's explicit preference:
mode: The actual active theme (always "light" or "dark"). This is what you use to determine how to style components or logic.userPrefersMode: The user's specific selection, which can be "light", "dark", or "system".If you need to know if a user has opted to follow the system settings, use userPrefersMode instead of mode.
Mode Watcher provides several automated theme management features:
prefers-color-scheme changes automatically.localStorage to save user preferences and sync themes across different tabs and windows.color-scheme CSS property (for scrollbars and form controls) and the theme-color meta tag (for the browser interface).The theme state is a readable state that holds the currently active theme as a string. Unlike mode (which is restricted to "light" or "dark"), theme allows you to define and track any custom string (e.g., "dracula", "retro", or "corporate"). This is useful for supporting multiple granular visual styles beyond simple light/dark modes. You can access the current value via theme.current and update it using setTheme.
<script lang="ts">
import { setTheme, theme } from "mode-watcher";
function cycleTheme() {
if (theme.current === "dracula") {
setTheme("retro");
} else {
setTheme("dracula");
}
}
</script>
<button onclick={cycleTheme}>{theme.current}</button>In Mode Watcher, Mode and Theme are distinct layers of customization that work together:
Represents the user's preference for the interface appearance. It controls the technical implementation of light/dark styles by:
light or dark class to the root <html> element.color-scheme (light or dark) for browser rendering.Possible mode values:
"light""dark""system" (follows the operating system's preference)Represents your application's design system (colors, typography, spacing, etc.). A single theme can contain both light and dark variants. Instead of creating separate themes for different modes (e.g., dracula-light and dracula-dark), you should provide one theme (e.g., dracula) that includes both variants. Mode Watcher will automatically select the correct variant based on the active mode.
Install the mode-watcher package using npm to add theme mode management to your Svelte application.
npm install mode-watcherIn SvelteKit applications, you can use createInitialModeExpression to generate a secure, inline JavaScript snippet that sets the initial color mode (light, dark, or system) before the page hydrates. This prevents the 'flash of unstyled content' (FOUC) where the theme jumps from light to dark (or vice versa) during page load.
This utility is specifically designed for environments with strict Content Security Policies (CSP) that require a nonce for inline scripts.
import { createInitialModeExpression } from "mode-watcher";
// Returns a string containing the inline script logic
const snippet = createInitialModeExpression();To use mode-watcher, add the ModeWatcher component to your root +layout.svelte file. This component automatically detects user preferences and applies the "dark" class and color-scheme style attribute to the html element.
track (boolean): If set to false, the component will stop tracking operating system preference changes.defaultMode (string): Sets a default mode (e.g., "dark") instead of automatic detection.themeColors (object): Configures the theme-color meta tag. Accepts an object with dark and light keys.Example configuration:
<script lang="ts">
import { ModeWatcher } from "mode-watcher";
let { children } = $props();
</script>
<ModeWatcher
track={true}
defaultMode="light"
themeColors={{ dark: "black", light: "white" }}
/>
{@render children()}To automatically apply mode and theme preferences in a SvelteKit application, add the ModeWatcher component to your root +layout.svelte file.
ModeWatcher performs the following actions:
light, dark, or system).dark) to the <html> element.color-scheme attribute on the <html> element.data-theme attribute.<script lang="ts">
import { ModeWatcher } from "mode-watcher";
let { children } = $props();
</script>
<ModeWatcher />
{@render children()}Install the mode-watcher package using npm to manage light and dark modes in your SvelteKit application.
npm install mode-watcherTo prepare your application for production, run the build script. Once the build is complete, you can use the preview script to run a local server that serves the production build for testing.
# Create a production version of your app
npm run build
# Preview the production build
npm run preview