Introducción

No todo sistema de temas necesita el poder completo de la API de Context. Para la mayoría de las aplicaciones, un enfoque más simple funciona mejor: estado reactivo a nivel de módulo con una función similar a un hook para acceder a él. Este patrón es utilizado por bibliotecas populares como svelte-themes, svelte-theme-select, y numerosas aplicaciones en producción.

El patrón de hook te proporciona un estado de tema global al que cualquier componente puede acceder sin proveedores, envoltorios ni prop drilling. Es más liviano, más fácil de probar y requiere menos código repetitivo que Context. Si no necesitas sobreescrituras de temas anidados (una tarjeta oscura en una página clara), este es el enfoque al que deberías recurrir primero.

Al finalizar este artículo, tendrás un sistema de temas completo que soporta modos claro, oscuro y de preferencia del sistema, persiste las elecciones del usuario entre sesiones, previene el temido destello del tema incorrecto, sincroniza entre pestañas del navegador y funciona con SSR de forma nativa—todo en menos de 100 líneas de código.

Si necesitas sobreescrituras de temas anidados—diferentes partes de tu árbol de componentes usando distintos temas simultáneamente—consulta Construyendo Sistemas de Temas Listos para Producción con Context. El comportamiento de ámbito de Context hace posibles los proveedores anidados, lo cual el estado a nivel de módulo no puede replicar.

¿Por Qué No Context?

Context resuelve un problema específico: pasar datos a través del árbol de componentes sin prop drilling, con la capacidad de sobrescribir valores en cualquier nivel. Para los temas, esto significa que podrías tener una sección promocional con tema oscuro dentro de una página con tema claro.

Pero la mayoría de las aplicaciones no necesitan eso. Tienen un tema global único que se aplica en todas partes. Para este caso común, Context agrega complejidad innecesaria. Necesitas un componente proveedor que envuelva tu aplicación, llamadas a getContext() que solo funcionan dentro de componentes, y ceremonial adicional que no aporta valor.

El estado a nivel de módulo en Svelte 5 te proporciona un estado reactivo verdaderamente global. Cualquier archivo puede importarlo. Cualquier componente puede leerlo o modificarlo. Sin proveedores, sin envoltorios, sin restricciones sobre dónde puedes acceder a él.

La Implementación Completa

Construyamos el sistema de temas completo. Crearemos un único archivo que maneja todo: gestión de estado, persistencia, detección de preferencia del sistema y la API pública.

// src/lib/theme.svelte.ts

import { browser } from '$app/environment'

// Types
export type ThemePreference = 'light' | 'dark' | 'system'
export type ResolvedTheme = 'light' | 'dark'

// Configuration
const STORAGE_KEY = 'theme-preference'
const COOKIE_MAX_AGE = 60 * 60 * 24 * 365 // 1 year

// Module-level reactive state
let preference = $state<ThemePreference>(getStoredPreference())
let systemTheme = $state<ResolvedTheme>(getSystemTheme())

/**
 * Reads the stored theme preference from localStorage.
 * Returns 'system' if nothing is stored or if not in browser.
 */
function getStoredPreference(): ThemePreference {
	if (!browser) return 'system'

	const stored = localStorage.getItem(STORAGE_KEY)
	if (stored === 'light' || stored === 'dark' || stored === 'system') {
		return stored
	}
	return 'system'
}

/**
 * Detects the operating system's color scheme preference.
 */
function getSystemTheme(): ResolvedTheme {
	if (!browser) return 'light'
	return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
}

/**
 * Applies the theme to the document.
 * Sets data-theme attribute and updates CSS color-scheme.
 */
function applyTheme(theme: ResolvedTheme): void {
	if (!browser) return

	document.documentElement.dataset.theme = theme
	document.documentElement.style.colorScheme = theme
}

/**
 * Persists the preference to localStorage and sets a cookie for SSR.
 */
function persistPreference(pref: ThemePreference): void {
	if (!browser) return

	localStorage.setItem(STORAGE_KEY, pref)
	document.cookie = `${STORAGE_KEY}=${pref};path=/;max-age=${COOKIE_MAX_AGE};SameSite=Lax`
}

// Initialize system preference listener
if (browser) {
	const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')

	mediaQuery.addEventListener('change', (event) => {
		systemTheme = event.matches ? 'dark' : 'light'

		// If following system, apply the new theme
		if (preference === 'system') {
			applyTheme(systemTheme)
		}
	})

	// Sync across tabs via storage event
	window.addEventListener('storage', (event) => {
		if (event.key === STORAGE_KEY && event.newValue) {
			const newPref = event.newValue as ThemePreference
			if (newPref === 'light' || newPref === 'dark' || newPref === 'system') {
				preference = newPref
				applyTheme(newPref === 'system' ? systemTheme : newPref)
			}
		}
	})
}

/**
 * The public API for theme management.
 * Call this function from any component to access theme state and actions.
 */
export function useTheme() {
	return {
		/** The user's preference: 'light', 'dark', or 'system' */
		get preference() {
			return preference
		},

		/** The actual theme being displayed: always 'light' or 'dark' */
		get resolvedTheme(): ResolvedTheme {
			return preference === 'system' ? systemTheme : preference
		},

		/** The system's current preference, regardless of user choice */
		get systemTheme() {
			return systemTheme
		},

		/** Convenience: true if currently displaying dark theme */
		get isDark() {
			return this.resolvedTheme === 'dark'
		},

		/** Convenience: true if currently displaying light theme */
		get isLight() {
			return this.resolvedTheme === 'light'
		},

		/** Convenience: true if following system preference */
		get isSystem() {
			return preference === 'system'
		},

		/** Set the theme preference */
		setTheme(newPreference: ThemePreference) {
			preference = newPreference
			persistPreference(newPreference)
			applyTheme(this.resolvedTheme)
		},

		/** Toggle between light and dark (exits system mode) */
		toggle() {
			const next = this.resolvedTheme === 'dark' ? 'light' : 'dark'
			this.setTheme(next)
		},

		/** Reset to system preference */
		reset() {
			this.setTheme('system')
		}
	}
}

Eso es todo el sistema de temas. Analicemos las decisiones clave.

Estado a Nivel de Módulo

Las declaraciones $state al inicio del archivo crean estado reactivo que vive a nivel de módulo. Este estado se comparte entre todas las importaciones—cada componente que llama a useTheme() obtiene los mismos valores reactivos. Cuando un componente cambia el tema, todos los demás se actualizan automáticamente.

let preference = $state<ThemePreference>(getStoredPreference())
let systemTheme = $state<ResolvedTheme>(getSystemTheme())

El Patrón useTheme

La función useTheme() retorna un objeto con getters. Esto es crucial para la reactividad. Si retornáramos los valores directamente, serían instantáneas que no se actualizan. Los getters aseguran que cada acceso lea el valor reactivo actual.

// ❌ Wrong - returns snapshot
export function useTheme() {
	return {
		resolvedTheme: preference === 'system' ? systemTheme : preference
	}
}

// ✅ Correct - getter reads current value
export function useTheme() {
	return {
		get resolvedTheme() {
			return preference === 'system' ? systemTheme : preference
		}
	}
}

Sincronización Entre Pestañas

El listener del evento storage sincroniza los cambios de tema entre pestañas del navegador. Cuando un usuario cambia el tema en una pestaña, todas las demás se actualizan de inmediato. Esto ocurre automáticamente con localStorage—solo necesitamos escuchar y reaccionar.

Prevención del Destello del Tema Incorrecto

El JavaScript mencionado se ejecuta después de la hidratación, lo que significa que hay un momento en que la página se muestra con el tema incorrecto. Los usuarios ven un destello molesto cuando se aplica el tema correcto. Lo prevenimos con un script en línea que se ejecuta antes de que la página se renderice.

Crea un componente que inyecte este script en el head del documento:

<!-- src/lib/components/Theme.svelte -->
<script lang="ts">
	const STORAGE_KEY = 'theme-preference'
</script>

<svelte:head>
	{@html `<script>
		(function() {
			try {
				const stored = localStorage.getItem('${STORAGE_KEY}');
				const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
				
				let theme;
				if (stored === 'dark' || stored === 'light') {
					theme = stored;
				} else {
					theme = systemDark ? 'dark' : 'light';
				}
				
				document.documentElement.dataset.theme = theme;
				document.documentElement.style.colorScheme = theme;
			} catch (e) {
				// localStorage might be blocked
			}
		})()
	</script>`}
</svelte:head>

Este script es pequeño y se ejecuta de forma sincrónica en el <head>, antes de que ocurra cualquier renderizado. Para cuando el navegador pinta los píxeles, el tema correcto ya está aplicado.

La directiva {@html} normalmente conlleva riesgos de XSS, pero aquí controlamos el contenido completo del string. La única parte dinámica es STORAGE_KEY, que es una constante que nosotros definimos. Ninguna entrada del usuario toca este script, lo que lo hace seguro.

Uso del Componente Theme

Agrégalo a tu layout raíz:

<!-- src/routes/+layout.svelte -->
<script>
	import Theme from '$lib/components/Theme.svelte'
	import '../app.css'

	let { children } = $props()
</script>

<Theme />

{@render children()}

El componente <Theme> no renderiza nada visible—solo inyecta el script de prevención de parpadeo.

SSR con Cookies y Hooks

Para soporte completo de renderizado del lado del servidor, podemos leer el tema desde una cookie y aplicarlo durante la generación del HTML usando los hooks del servidor de SvelteKit. Esto elimina cualquier destello incluso antes de que se cargue JavaScript.

// src/hooks.server.ts
import type { Handle } from '@sveltejs/kit'

export const handle: Handle = async ({ event, resolve }) => {
	const theme = event.cookies.get('theme-preference')

	// If no valid theme cookie, let client-side handle it
	if (!theme || !['light', 'dark', 'system'].includes(theme)) {
		return resolve(event)
	}

	// For 'system', we can't know the preference on server
	// Default to light, the inline script will correct if needed
	const resolved = theme === 'system' ? 'light' : theme

	return resolve(event, {
		transformPageChunk: ({ html }) => {
			return html.replace('data-theme=""', `data-theme="${resolved}"`)
		}
	})
}

Actualiza tu app.html para incluir un atributo data-theme vacío:

<!-- src/app.html -->
<!DOCTYPE html>
<html lang="en" data-theme="">
	<head>
		<meta charset="utf-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1" />
		%sveltekit.head%
	</head>
	<body>
		<div style="display: contents">%sveltekit.body%</div>
	</body>
</html>

Usar transformPageChunk significa que las páginas con diferentes temas tendrán HTML diferente. Esto puede complicar el almacenamiento en caché. Para sitios estáticos o caché en CDN, podrías preferir el enfoque solo del lado del cliente con el script en línea.

La biblioteca svelte-theme-select evita específicamente transformPageChunk por esta razón, manejando todo del lado del cliente con el enfoque del script en línea.

Construyendo Controles de Tema

Con useTheme() disponible, construir controles de UI es sencillo.

Botón de Alternancia Simple

<!-- src/lib/components/ThemeToggle.svelte -->
<script lang="ts">
	import { useTheme } from '$lib/theme.svelte.js'

	const theme = useTheme()
</script>

<button
	type="button"
	onclick={() => theme.toggle()}
	aria-label={theme.isDark ? 'Switch to light mode' : 'Switch to dark mode'}
	class="theme-toggle"
>
	{#if theme.isDark}
		<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
			<path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
		</svg>
	{:else}
		<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
			<circle cx="12" cy="12" r="5" />
			<line x1="12" y1="1" x2="12" y2="3" />
			<line x1="12" y1="21" x2="12" y2="23" />
			<line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
			<line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
			<line x1="1" y1="12" x2="3" y2="12" />
			<line x1="21" y1="12" x2="23" y2="12" />
			<line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
			<line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
		</svg>
	{/if}
</button>

<style>
	.theme-toggle {
		display: flex;
		align-items: center;
		justify-content: center;
		width: 40px;
		height: 40px;
		padding: 0;
		border: none;
		border-radius: 8px;
		background: var(--color-surface, #f1f5f9);
		color: var(--color-foreground, #0f172a);
		cursor: pointer;
		transition:
			background-color 0.2s,
			transform 0.2s;
	}

	.theme-toggle:hover {
		background: var(--color-surface-hover, #e2e8f0);
		transform: scale(1.05);
	}

	.theme-toggle svg {
		width: 20px;
		height: 20px;
	}
</style>

Selector de Tres Opciones

<!-- src/lib/components/ThemeSelector.svelte -->
<script lang="ts">
	import { useTheme } from '$lib/theme.svelte.js'
	import type { ThemePreference } from '$lib/theme.svelte.js'

	const theme = useTheme()

	const options: { value: ThemePreference; label: string; icon: string }[] = [
		{ value: 'light', label: 'Light', icon: '☀️' },
		{ value: 'dark', label: 'Dark', icon: '🌙' },
		{ value: 'system', label: 'System', icon: '💻' }
	]
</script>

<div class="theme-selector" role="radiogroup" aria-label="Theme selection">
	{#each options as option (option.value)}
		<button
			type="button"
			role="radio"
			aria-checked={theme.preference === option.value}
			class="option"
			class:selected={theme.preference === option.value}
			onclick={() => theme.setTheme(option.value)}
		>
			<span class="icon">{option.icon}</span>
			<span class="label">{option.label}</span>
		</button>
	{/each}
</div>

{#if theme.isSystem}
	<p class="system-note">
		Currently using <strong>{theme.resolvedTheme}</strong> based on system settings.
	</p>
{/if}

<style>
	.theme-selector {
		display: inline-flex;
		gap: 4px;
		padding: 4px;
		border-radius: 12px;
		background: var(--color-surface, #f1f5f9);
	}

	.option {
		display: flex;
		align-items: center;
		gap: 6px;
		padding: 8px 12px;
		border: none;
		border-radius: 8px;
		background: transparent;
		color: var(--color-foreground, #0f172a);
		font-size: 14px;
		cursor: pointer;
		transition: background-color 0.2s;
	}

	.option:hover:not(.selected) {
		background: var(--color-surface-hover, #e2e8f0);
	}

	.option.selected {
		background: var(--color-background, #ffffff);
		box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
	}

	.icon {
		font-size: 16px;
	}

	.system-note {
		margin-top: 8px;
		font-size: 12px;
		color: var(--color-foreground-muted, #64748b);
	}
</style>

Select Desplegable (estilo daisyUI)

Para aplicaciones con muchos temas (como los más de 35 temas de daisyUI):

<!-- src/lib/components/ThemeDropdown.svelte -->
<script lang="ts">
	import { useTheme } from '$lib/theme.svelte.js'
	import type { ThemePreference } from '$lib/theme.svelte.js'

	const theme = useTheme()

	const themes: ThemePreference[] = ['light', 'dark', 'system']

	function handleChange(event: Event) {
		const select = event.target as HTMLSelectElement
		theme.setTheme(select.value as ThemePreference)
	}
</script>

<select
	value={theme.preference}
	onchange={handleChange}
	class="theme-dropdown"
	aria-label="Select theme"
>
	<option value="" disabled>Choose a theme</option>
	{#each themes as t (t)}
		<option value={t}>{t.charAt(0).toUpperCase() + t.slice(1)}</option>
	{/each}
</select>

<style>
	.theme-dropdown {
		padding: 8px 12px;
		border: 1px solid var(--color-border, #e2e8f0);
		border-radius: 8px;
		background: var(--color-surface, #f8fafc);
		color: var(--color-foreground, #0f172a);
		font-size: 14px;
		cursor: pointer;
	}
</style>

Configuración de CSS

Tu CSS global necesita definir las variables del tema:

/* src/app.css */

:root {
	/* Light theme (default) */
	--color-background: #ffffff;
	--color-surface: #f8fafc;
	--color-surface-hover: #f1f5f9;
	--color-foreground: #0f172a;
	--color-foreground-muted: #64748b;
	--color-primary: #3b82f6;
	--color-border: #e2e8f0;
}

:root[data-theme='dark'] {
	--color-background: #0f172a;
	--color-surface: #1e293b;
	--color-surface-hover: #334155;
	--color-foreground: #f8fafc;
	--color-foreground-muted: #94a3b8;
	--color-primary: #60a5fa;
	--color-border: #334155;
}

html,
body {
	margin: 0;
	background-color: var(--color-background);
	color: var(--color-foreground);
	transition:
		background-color 0.3s,
		color 0.3s;
}

Uso del Tema Fuera de Componentes

Una ventaja del patrón de hook sobre Context: puedes usarlo en cualquier lugar, no solo en componentes.

// src/lib/chart-config.ts
import { useTheme } from '$lib/theme.svelte.js'

export function getChartColors() {
	const theme = useTheme()

	return {
		background: theme.isDark ? '#1e293b' : '#ffffff',
		gridLines: theme.isDark ? '#334155' : '#e2e8f0',
		text: theme.isDark ? '#f8fafc' : '#0f172a',
		primary: theme.isDark ? '#60a5fa' : '#3b82f6'
	}
}

// src/lib/api.ts
import { useTheme } from '$lib/theme.svelte.js'

export function getPreferredImageVariant(baseUrl: string) {
	const theme = useTheme()
	return `${baseUrl}?variant=${theme.resolvedTheme}`
}

Estructura Completa del Proyecto

src/
├── lib/
│   ├── theme.svelte.ts          # Core theme logic
│   └── components/
│       ├── Theme.svelte         # Flash prevention script
│       ├── ThemeToggle.svelte   # Simple toggle button
│       ├── ThemeSelector.svelte # Three-way selector
│       └── ThemeDropdown.svelte # Dropdown select
├── routes/
│   └── +layout.svelte           # Root layout with Theme component
├── hooks.server.ts              # Optional SSR cookie handling
├── app.html                     # HTML template
└── app.css                      # Theme CSS variables

Errores Comunes

Retornar valores en lugar de getters:

// ❌ Wrong - loses reactivity
export function useTheme() {
	return { isDark: preference === 'dark' }
}

// ✅ Correct - maintains reactivity
export function useTheme() {
	return {
		get isDark() {
			return preference === 'dark'
		}
	}
}

Olvidar el componente Theme:

Sin el script en línea del componente <Theme>, los usuarios verán un destello del tema incorrecto en cada carga de página. Siempre inclúyelo en tu layout raíz.

No manejar errores de localStorage:

En la navegación privada o con configuraciones de privacidad estrictas, localStorage puede lanzar errores. Siempre envuelve en try/catch:

function getStoredPreference(): ThemePreference {
	if (!browser) return 'system'
	try {
		return (localStorage.getItem(STORAGE_KEY) as ThemePreference) || 'system'
	} catch {
		return 'system'
	}
}

Consideraciones de Rendimiento

El patrón de hook es extremadamente liviano. No hay árbol de proveedores, no hay búsquedas de contexto, solo acceso directo al estado a nivel de módulo. La implementación completa tiene menos de 100 líneas y agrega un tamaño de bundle mínimo.

El script en línea para prevenir el destello pesa aproximadamente 300 bytes minificado. Se ejecuta de forma síncrona pero tarda microsegundos en completarse—simplemente lee el localStorage y establece un atributo de datos.

Las propiedades personalizadas de CSS son las campeonas del rendimiento aquí. Cuando cambias --color-background en la raíz del documento, el navegador maneja todas las actualizaciones internamente. Sin bucles de JavaScript, sin manipulación del DOM, solo la optimización nativa del navegador.

Cuándo Usar Context en su Lugar

El patrón de hook cubre la mayoría de los casos de uso, pero Context tiene una capacidad que le falta: los ámbitos anidados. Si necesitas una tarjeta promocional oscura en una página clara, o un editor de código claro en una aplicación oscura, esos requieren que diferentes partes de tu árbol tengan diferentes valores de tema simultáneamente.

El patrón de proveedor de Context permite esto:

<!-- Page is light, but this card is dark -->
<ThemeProvider forceTheme="dark">
	<PromoCard />
</ThemeProvider>

Los componentes dentro del proveedor anidado obtienen el tema oscuro forzado, mientras que todo lo demás usa el tema de la página. El estado a nivel de módulo no puede hacer esto—es global por naturaleza.

Para una implementación completa de temas basados en Context con anulaciones anidadas, consulta Construyendo Sistemas de Temas Listos para Producción con Context.

Conclusión

El patrón de hook useTheme() ofrece el camino más sencillo para la gestión de temas en Svelte 5. El estado reactivo a nivel de módulo te da acceso global sin proveedores. El script en línea previene el destello. La sincronización entre pestañas viene gratis con los eventos de localStorage. Y todo encaja en menos de 100 líneas de código.

Para la gran mayoría de las aplicaciones—donde un tema se aplica globalmente—este es el enfoque correcto. Recurre a Context solo cuando necesites específicamente anulaciones de temas anidados, e incluso entonces, considera si esa complejidad vale la pena.

El mejor código suele ser el código que no escribes. Empieza simple y agrega complejidad solo cuando tengas una necesidad concreta de ella.

Puntos Clave

$state a nivel de módulo crea estado reactivo compartido globalmente que cualquier archivo puede importar.
Retorna getters, no valores desde tu función hook para mantener la reactividad.
El script en línea en <svelte:head> previene el destello al aplicar el tema antes del renderizado.
Los eventos de Storage proveen sincronización entre pestañas de forma gratuita.
Las cookies habilitan el SSR pero considera las implicaciones de caché de transformPageChunk.
Las propiedades personalizadas de CSS son la forma más eficiente de aplicar colores de tema.
Context solo es necesario para anulaciones de temas anidados—empieza con el patrón de hook.