Introdução

Nem todo sistema de temas precisa de todo o poder da Context API. Para a maioria das aplicações, uma abordagem mais simples funciona melhor: estado reativo em nível de módulo com uma função semelhante a um hook para acessá-lo. Esse padrão é utilizado por bibliotecas populares como svelte-themes, svelte-theme-select, e inúmeras aplicações em produção.

O padrão de hook fornece um estado global de tema que qualquer componente pode acessar sem provedores, wrappers ou prop drilling. É mais leve, mais fácil de testar e exige menos boilerplate do que Context. Se você não precisa de sobreposições de tema aninhadas (um card escuro em uma página clara), essa é a abordagem que você deve experimentar primeiro.

Ao final deste artigo, você terá um sistema de temas completo que suporta modos claro, escuro e preferência do sistema, persiste as escolhas do usuário entre sessões, previne o temido flash do tema errado, sincroniza entre abas do navegador e funciona com SSR sem configurações adicionais — tudo em menos de 100 linhas de código.

Se você precisar de sobreposições de tema aninhadas—partes diferentes da sua árvore de componentes usando temas diferentes simultaneamente—consulte Construindo Sistemas de Temas Prontos para Produção com Context. O comportamento de escopo do Context torna possíveis provedores aninhados, o que o estado em nível de módulo não consegue replicar.

Por Que Não Context?

Context resolve um problema específico: passar dados pela árvore de componentes sem prop drilling, com a capacidade de sobrescrever valores em qualquer nível. Para temas, isso significa que você poderia ter uma seção promocional com tema escuro dentro de uma página com tema claro.

Mas a maioria das aplicações não precisa disso. Elas têm um tema global único que se aplica em todo lugar. Para esse caso comum, Context adiciona complexidade desnecessária. Você precisa de um componente provedor envolvendo sua aplicação, chamadas de getContext() que só funcionam dentro de componentes, e cerimônia extra que não agrega valor.

O estado em nível de módulo no Svelte 5 oferece um estado reativo verdadeiramente global. Qualquer arquivo pode importá-lo. Qualquer componente pode ler ou modificá-lo. Sem provedores, sem wrappers, sem restrições sobre onde você pode acessá-lo.

A Implementação Completa

Vamos construir todo o sistema de temas. Criaremos um único arquivo que trata de tudo: gerenciamento de estado, persistência, detecção de preferência do sistema e a 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')
		}
	}
}

Esse é o sistema de temas completo. Vamos detalhar as principais decisões.

Estado em Nível de Módulo

As declarações $state no topo do arquivo criam estado reativo que reside no nível do módulo. Esse estado é compartilhado entre todas as importações — cada componente que chama useTheme() obtém os mesmos valores reativos. Quando um componente muda o tema, todos os outros atualizam automaticamente.

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

O Padrão useTheme

A função useTheme() retorna um objeto com getters. Isso é fundamental para a reatividade. Se retornássemos os valores diretamente, eles seriam snapshots que não se atualizam. Os getters garantem que cada acesso leia o valor reativo atual.

// ❌ 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
		}
	}
}

Sincronização Entre Abas

O listener do evento storage sincroniza as mudanças de tema entre as abas do navegador. Quando um usuário muda o tema em uma aba, todas as outras abas atualizam imediatamente. Isso acontece automaticamente com localStorage — precisamos apenas ouvir e reagir.

Prevenindo o Flash do Tema Errado

O JavaScript acima é executado após a hidratação, o que significa que há um momento em que a página é exibida com o tema errado. Os usuários veem um flash perturbador enquanto o tema correto é aplicado. Prevenimos isso com um script inline que é executado antes da renderização da página.

Crie um componente que injeta esse script no head do 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 é pequeno e executa de forma síncrona no <head>, antes de qualquer renderização. Quando o navegador renderiza os pixels, o tema correto já está aplicado.

A diretiva {@html} normalmente apresenta riscos de XSS, mas aqui controlamos todo o conteúdo da string. A única parte dinâmica é STORAGE_KEY, que é uma constante que definimos. Nenhuma entrada do usuário toca este script, tornando-o seguro.

Usando o Componente de Tema

Adicione-o ao seu layout raiz:

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

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

<Theme />

{@render children()}

O componente <Theme> não renderiza nada visível — ele apenas injeta o script de prevenção de flash.

SSR com Cookies e Hooks

Para suporte completo a renderização do lado do servidor, podemos ler o tema a partir de um cookie e aplicá-lo durante a geração do HTML usando os server hooks do SvelteKit. Isso elimina qualquer flash mesmo antes de o JavaScript carregar.

// 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}"`)
		}
	})
}

Atualize seu app.html para incluir um atributo data-theme vazio:

<!-- 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 páginas com temas diferentes terão HTML diferente. Isso pode complicar o cache. Para sites estáticos ou cache em CDN, você pode preferir a abordagem apenas no cliente com o script inline.

A biblioteca svelte-theme-select evita especificamente transformPageChunk por esse motivo, tratando tudo no lado do cliente com a abordagem de script inline.

Construindo Controles de Tema

Com useTheme() disponível, construir controles de UI é simples.

Botão de Alternância Simples

<!-- 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>

Seletor de Três Opções

<!-- 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>

Para aplicações com muitos temas (como os 35+ temas do 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>

Configuração do CSS

Seu CSS global precisa definir as variáveis de 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;
}

Usando o Tema Fora de Componentes

Uma vantagem do padrão de hook sobre Context: você pode usá-lo em qualquer lugar, não apenas em 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}`
}

Estrutura Completa do Projeto

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

Erros Comuns

Retornar valores em vez de getters:

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

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

Esquecer o componente Theme:

Sem o script inline do componente <Theme>, os usuários verão um flash do tema errado a cada carregamento de página. Sempre inclua-o no seu layout raiz.

Não tratar erros do localStorage:

Em navegação privada ou com configurações rígidas de privacidade, o localStorage pode lançar erros. Sempre envolva em try/catch:

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

Considerações de Performance

O padrão de hook é extremamente leve. Não há árvore de providers, nem buscas de contexto, apenas acesso direto ao estado no nível do módulo. A implementação completa tem menos de 100 linhas e adiciona um tamanho de bundle mínimo.

O script inline para prevenção de flash tem cerca de 300 bytes minificado. Ele é executado de forma síncrona, mas opera em microssegundos — apenas lendo o localStorage e definindo um atributo de dados.

As propriedades customizadas do CSS são o grande destaque de performance aqui. Quando você altera --color-background no elemento raiz do documento, o navegador cuida de todas as atualizações internamente. Sem loops de JavaScript, sem manipulação do DOM, apenas otimização nativa do navegador.

Quando Usar Context em Vez Disso

O padrão de hook cobre a maioria dos casos de uso, mas o Context tem uma capacidade que ele não possui: escopos aninhados. Se você precisa de um cartão promocional escuro em uma página clara, ou um editor de código claro em um app escuro, esses casos exigem que diferentes partes da sua árvore tenham valores de tema diferentes simultaneamente.

O padrão de provider do Context possibilita isso:

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

Os componentes dentro do provider aninhado recebem o tema escuro forçado, enquanto todo o restante usa o tema da página. O estado no nível do módulo não consegue fazer isso — é global por natureza.

Para uma implementação completa de tematização baseada em Context com sobrescritas aninhadas, veja Construindo Sistemas de Tema Prontos para Produção com Context.

Conclusão

O padrão de hook useTheme() oferece o caminho mais simples para o gerenciamento de temas no Svelte 5. O estado reativo no nível do módulo fornece acesso global sem providers. O script inline previne o flash. A sincronização entre abas vem gratuitamente com os eventos do localStorage. E tudo isso cabe em menos de 100 linhas de código.

Para a grande maioria das aplicações — onde um tema se aplica globalmente — esta é a abordagem correta. Recorra ao Context apenas quando você precisar especificamente de sobrescritas de tema aninhadas, e mesmo assim, considere se essa complexidade vale a pena.

O melhor código é frequentemente o código que você não escreve. Comece simples e adicione complexidade apenas quando tiver uma necessidade concreta para isso.

Principais Conclusões

$state no nível do módulo cria estado reativo compartilhado globalmente que qualquer arquivo pode importar.
Retorne getters, não valores da sua função de hook para manter a reatividade.
Script inline em <svelte:head> previne o flash aplicando o tema antes da renderização.
Eventos de storage fornecem sincronização entre abas gratuitamente.
Cookies habilitam SSR, mas considere as implicações de cache do transformPageChunk.
Propriedades customizadas do CSS são a forma mais performática de aplicar cores de tema.
Context só é necessário para sobrescritas de tema aninhadas — comece com o padrão de hook.

Introdução

Por Que Não Context?

A Implementação Completa

Estado em Nível de Módulo

O Padrão useTheme

Sincronização Entre Abas

Prevenindo o Flash do Tema Errado

Usando o Componente de Tema

SSR com Cookies e Hooks

Construindo Controles de Tema

Botão de Alternância Simples

Seletor de Três Opções

Configuração do CSS

Usando o Tema Fora de Componentes

Estrutura Completa do Projeto

Erros Comuns

Considerações de Performance

Quando Usar Context em Vez Disso

Conclusão

Principais Conclusões

Leitura Adicional

Bibliotecas que Usam Este Padrão

Artigos Relacionados

Documentação Oficial

Introdução

Por Que Não Context?

A Implementação Completa

Estado em Nível de Módulo

O Padrão useTheme

Sincronização Entre Abas

Prevenindo o Flash do Tema Errado

Usando o Componente de Tema

SSR com Cookies e Hooks

Construindo Controles de Tema

Botão de Alternância Simples

Seletor de Três Opções

Seleção por Dropdown (estilo daisyUI)

Configuração do CSS

Usando o Tema Fora de Componentes

Estrutura Completa do Projeto

Erros Comuns

Considerações de Performance

Quando Usar Context em Vez Disso

Conclusão

Principais Conclusões

Leitura Adicional

Bibliotecas que Usam Este Padrão

Artigos Relacionados

Documentação Oficial