Entendendo o Contexto do Document Object Model

Antes de mergulhar na mecânica do svelte:document, é essencial compreender por que esse elemento especial existe e qual espaço de problema ele ocupa na arquitetura do Svelte. O Document Object Model do navegador apresenta uma estrutura hierárquica onde o objeto document se posiciona como o nó raiz contendo todo o conteúdo da página, distinto do objeto window (que representa a janela do navegador em si) e do elemento body (o contêiner visível para o conteúdo da página).

Muitos eventos do navegador sobem por essa hierarquia, mas certos eventos disparam especificamente no objeto document e nunca chegam ao window. O evento visibilitychange representa o exemplo mais comum — esse evento dispara exclusivamente no document quando os usuários alternam abas, minimizam navegadores ou navegam para outro lugar. Da mesma forma, propriedades como activeElement (que rastreia qual elemento tem foco atualmente) existem apenas no document, tornando o acesso direto ao documento necessário para certos comportamentos de aplicação.

O elemento especial <svelte:document> do Svelte fornece acesso declarativo a essa funcionalidade em nível de documento, mantendo os princípios do Svelte de limpeza automática, segurança para renderização no servidor e suporte a bindings reativos. Sem essa abstração, os desenvolvedores precisariam conectar manualmente ouvintes de eventos em hooks de ciclo de vida, lembrar de limpá-los na destruição do componente e lidar com ambientes SSR onde document não existe.

Sintaxe Básica e Requisitos de Posicionamento

O elemento <svelte:document> segue uma regra estrita de posicionamento compartilhada com seus elementos especiais irmãos <svelte:window> e <svelte:body>: ele deve aparecer no nível superior do seu componente, nunca aninhado dentro de blocos, elementos ou estruturas condicionais.

<script>
	let visibilityState = $state('visible')

	function handleVisibilityChange() {
		visibilityState = document.visibilityState
		console.log(`Page visibility changed to: ${visibilityState}`)
	}
</script>

<!-- Correct: top-level placement -->
<svelte:document onvisibilitychange={handleVisibilityChange} />

<main>
	<p>Current visibility: {visibilityState}</p>
</main>

Tentar colocar <svelte:document> dentro de blocos condicionais ou elementos acionará um erro do compilador. Essa restrição existe porque o Svelte precisa registrar ouvintes em nível de documento durante a inicialização do componente, não condicionalmente durante a renderização. O compilador impõe isso para evitar comportamentos confusos em tempo de execução onde os ouvintes podem ou não existir com base em condições de renderização.

<script>
	let showDocumentHandler = $state(true);
</script>

<!-- NCORRECT: This will cause a compiler error -->
{#if showDocumentHandler}
	<svelte:document onvisibilitychange={handleChange} />
{/if}

<!--INCORRECT: Cannot nest inside elements -->
<div>
	<svelte:document onvisibilitychange={handleChange} />
</div>

A justificativa por trás dessa restrição se conecta à estratégia de compilação do Svelte. Elementos especiais como <svelte:document> compilam para chamadas diretas à API do DOM durante a inicialização do componente. Colocá-los dentro de blocos condicionais exigiria gerenciamento dinâmico de ouvintes com coordenação complexa de ciclo de vida, prejudicando a simplicidade que torna esses elementos valiosos.

Manipulação de Eventos no Document

O caso de uso principal para <svelte:document> envolve ouvir eventos específicos do documento. O Svelte 5 usa a sintaxe moderna oneventname em vez da diretiva legada on:eventname, alinhando-se com padrões nativos do DOM e melhorando o desempenho por meio de delegação de eventos.

O Evento visibilitychange

O evento visibilitychange representa o exemplo canônico de uso do <svelte:document>. Esse evento dispara sempre que o estado de visibilidade da página muda — quando os usuários alternam abas do navegador, minimizam janelas ou navegam para diferentes aplicações.

<script>
	let isPageVisible = $state(true)
	let lastVisibilityChange = $state(null)
	let hiddenDuration = $state(0)
	let hiddenStartTime = $state(null)

	function handleVisibilityChange(event) {
		const now = new Date()
		lastVisibilityChange = now.toLocaleTimeString()

		if (document.visibilityState === 'hidden') {
			isPageVisible = false
			hiddenStartTime = Date.now()
		} else {
			isPageVisible = true
			if (hiddenStartTime) {
				hiddenDuration += Date.now() - hiddenStartTime
				hiddenStartTime = null
			}
		}
	}
</script>

<svelte:document onvisibilitychange={handleVisibilityChange} />

<div class="visibility-tracker">
	<div class={{ status: true, visible: isPageVisible, hidden: !isPageVisible }}>
		{isPageVisible ? '👁️ Page Visible' : '🙈 Page Hidden'}
	</div>

	{#if lastVisibilityChange}
		<p>Last change: {lastVisibilityChange}</p>
	{/if}

	<p>Total time hidden: {Math.round(hiddenDuration / 1000)} seconds</p>
</div>

<style>
	.status {
		padding: 1rem;
		border-radius: 0.5rem;
		font-weight: bold;
		transition: all 0.3s ease;
	}

	.visible {
		background: #d4edda;
		color: #155724;
	}

	.hidden {
		background: #f8d7da;
		color: #721c24;
	}
</style>

Esse padrão se mostra inestimável para aplicações que precisam pausar operações custosas quando os usuários navegam para outro lugar. Players de vídeo podem pausar a reprodução, sistemas de analytics podem rastrear o tempo de engajamento com precisão e aplicações em tempo real podem reduzir o polling do servidor quando a página não está visível.

Eventos de Seleção e Área de Transferência

O objeto document serve como alvo para vários eventos relacionados a seleção e área de transferência que não sobem até o window:

<script>
	let selectedText = $state('')
	let selectionCount = $state(0)
	let clipboardHistory = $state([])

	function handleSelectionChange() {
		const selection = document.getSelection()
		const text = selection?.toString() || ''

		if (text !== selectedText) {
			selectedText = text
			if (text) {
				selectionCount++
			}
		}
	}

	function handleCopy(event) {
		const copiedText = document.getSelection()?.toString()
		if (copiedText) {
			clipboardHistory = [
				{ text: copiedText, timestamp: new Date() },
				...clipboardHistory.slice(0, 9)
			]
		}
	}

	function handlePaste(event) {
		const pastedData = event.clipboardData?.getData('text')
		console.log('User pasted:', pastedData)
	}
</script>

<svelte:document
	onselectionchange={handleSelectionChange}
	oncopy={handleCopy}
	onpaste={handlePaste}
/>

<article>
	<h2>Text Selection Tracker</h2>
	<p>
		Select any text on this page to see it tracked below. The selection change event fires on the
		document whenever the user's text selection changes, whether by mouse, keyboard, or programmatic
		manipulation.
	</p>

	<p>
		Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum ante ipsum primis in
		faucibus orci luctus et ultrices posuere cubilia curae; Praesent euismod neque non eros
		efficitur, at consequat lorem facilisis.
	</p>
</article>

<aside class="selection-info">
	<h3>Current Selection</h3>
	<pre>{selectedText || '(nothing selected)'}</pre>
	<p>Total selections made: {selectionCount}</p>

	{#if clipboardHistory.length > 0}
		<h3>Copy History</h3>
		<ul>
			{#each clipboardHistory as entry}
				<li>
					<span class="timestamp">{entry.timestamp.toLocaleTimeString()}</span>
					<code>{entry.text.slice(0, 50)}{entry.text.length > 50 ? '...' : ''}</code>
				</li>
			{/each}
		</ul>
	{/if}
</aside>

Eventos de Tela Cheia

Gerenciar o estado de tela cheia requer manipulação de eventos em nível de documento, pois os eventos fullscreenchange e fullscreenerror disparam no document:

<script>
	let isFullscreen = $state(false)
	let fullscreenElement = $state(null)
	let fullscreenError = $state(null)

	function handleFullscreenChange() {
		isFullscreen = !!document.fullscreenElement
		fullscreenElement = document.fullscreenElement?.tagName || null

		if (!isFullscreen) {
			console.log('Exited fullscreen mode')
		}
	}

	function handleFullscreenError(event) {
		fullscreenError = 'Failed to enter fullscreen mode. The browser may have blocked the request.'
		setTimeout(() => (fullscreenError = null), 5000)
	}

	async function toggleFullscreen(element) {
		try {
			if (!document.fullscreenElement) {
				await element.requestFullscreen()
			} else {
				await document.exitFullscreen()
			}
		} catch (err) {
			fullscreenError = err.message
		}
	}

	let videoContainer
</script>

<svelte:document
	onfullscreenchange={handleFullscreenChange}
	onfullscreenerror={handleFullscreenError}
/>

<div class="fullscreen-demo">
	<div bind:this={videoContainer} class={['video-container', isFullscreen && 'fullscreen']}>
		<div class="video-placeholder">
			<p>Video Content Area</p>
			<p class="status">
				{isFullscreen ? 'Currently in fullscreen' : 'Normal view'}
			</p>
		</div>

		<button onclick={() => toggleFullscreen(videoContainer)}>
			{isFullscreen ? 'Exit Fullscreen' : 'Enter Fullscreen'}
		</button>
	</div>

	{#if fullscreenError}
		<div class="error-message" role="alert">
			{fullscreenError}
		</div>
	{/if}

	{#if fullscreenElement}
		<p>Fullscreen element: <code>&lt;{fullscreenElement.toLowerCase()}&gt;</code></p>
	{/if}
</div>

Bindings Reativos: Lendo o Estado do Document

Além da manipulação de eventos, <svelte:document> fornece bindings reativos para quatro propriedades do documento. Ao contrário de muitos bindings de elementos no Svelte, todos os bindings de documento são somente leitura — você pode observar seus valores, mas não pode defini-los programaticamente por meio de binding.

Binding activeElement

A propriedade activeElement rastreia qual elemento do DOM tem foco atualmente. Esse binding é atualizado reativamente conforme os usuários navegam pelos campos de formulário com Tab, clicam em elementos interativos ou quando o foco é movido programaticamente:

<script>
	let activeElement = $state(null)
	let focusHistory = $state([])

	$effect(() => {
		if (activeElement) {
			const elementDescription = describeElement(activeElement)

			if (focusHistory[0]?.description !== elementDescription) {
				focusHistory = [
					{ description: elementDescription, time: new Date() },
					...focusHistory.slice(0, 19)
				]
			}
		}
	})

	function describeElement(el) {
		if (!el) return 'None'

		const tag = el.tagName.toLowerCase()
		const id = el.id ? `#${el.id}` : ''
		const className = el.className ? `.${el.className.split(' ')[0]}` : ''
		const name = el.name ? `[name="${el.name}"]` : ''
		const type = el.type ? `[type="${el.type}"]` : ''

		return `${tag}${id}${className}${name}${type}`
	}
</script>

<svelte:document bind:activeElement />

<div class="focus-tracker">
	<div class="current-focus">
		<h3>Currently Focused Element</h3>
		<code class="element-display">
			{describeElement(activeElement)}
		</code>
	</div>

	<form class="demo-form">
		<h3>Test Form</h3>

		<div class="field">
			<label for="username">Username</label>
			<input type="text" id="username" name="username" placeholder="Enter username" />
		</div>

		<div class="field">
			<label for="email">Email</label>
			<input type="email" id="email" name="email" placeholder="Enter email" />
		</div>

		<div class="field">
			<label for="password">Password</label>
			<input type="password" id="password" name="password" placeholder="Enter password" />
		</div>

		<div class="field">
			<label for="role">Role</label>
			<select id="role" name="role">
				<option>Developer</option>
				<option>Designer</option>
				<option>Manager</option>
			</select>
		</div>

		<div class="actions">
			<button type="button">Cancel</button>
			<button type="submit">Submit</button>
		</div>
	</form>

	<div class="focus-history">
		<h3>Focus History</h3>
		<ol reversed>
			{#each focusHistory as entry}
				<li>
					<code>{entry.description}</code>
					<small>{entry.time.toLocaleTimeString()}</small>
				</li>
			{/each}
		</ol>
	</div>
</div>

O binding activeElement viabiliza padrões sofisticados de gerenciamento de foco, aprimoramentos de acessibilidade e sistemas de navegação por teclado. É particularmente valioso para diálogos modais que precisam prender o foco, implementações de links de salto e validação de formulários complexa que responde ao foco em campos.

Binding visibilityState

Enquanto o evento visibilitychange informa quando a visibilidade muda, o binding visibilityState fornece acesso reativo ao estado atual:

<script>
	let visibilityState = $state('visible')
	let pollInterval = $state(null)
	let dataFetchCount = $state(0)

	$effect(() => {
		if (visibilityState === 'visible') {
			pollInterval = setInterval(() => {
				fetchLatestData()
			}, 5000)

			fetchLatestData()

			return () => {
				clearInterval(pollInterval)
			}
		} else {
			console.log('Polling paused - page hidden')
		}
	})

	async function fetchLatestData() {
		dataFetchCount++
		console.log(`Fetch #${dataFetchCount} - Page is ${visibilityState}`)
	}
</script>

<svelte:document bind:visibilityState />

<div class="polling-demo">
	<h2>Visibility-Aware Polling</h2>

	<div class="status-card" data-visibility={visibilityState}>
		<span class="indicator"></span>
		<span>Page is {visibilityState}</span>
	</div>

	<p>Data fetches performed: <strong>{dataFetchCount}</strong></p>

	<p class="explanation">
		This component automatically pauses API polling when you switch to another tab and resumes when
		you return. Try switching tabs and watch the fetch count!
	</p>
</div>

<style>
	.status-card {
		display: flex;
		align-items: center;
		gap: 0.5rem;
		padding: 1rem;
		border-radius: 0.5rem;
		background: #f0f0f0;
	}

	.indicator {
		width: 12px;
		height: 12px;
		border-radius: 50%;
		background: #28a745;
	}

	[data-visibility='hidden'] .indicator {
		background: #dc3545;
	}
</style>

Bindings fullscreenElement e pointerLockElement

Esses bindings fornecem acesso reativo ao elemento atual em tela cheia e a qualquer elemento que tenha capturado o bloqueio de ponteiro:

<script>
	let fullscreenElement = $state(null)
	let pointerLockElement = $state(null)

	let gameCanvas

	$effect(() => {
		if (pointerLockElement === gameCanvas) {
			console.log('Game has pointer lock - mouse movement now controls the game')
		}
	})

	function startGame() {
		gameCanvas?.requestPointerLock()
	}

	function handleMouseMove(event) {
		if (pointerLockElement === gameCanvas) {
			console.log('Mouse delta:', event.movementX, event.movementY)
		}
	}
</script>

<svelte:document bind:fullscreenElement bind:pointerLockElement />

<div class="game-container">
	<canvas
		bind:this={gameCanvas}
		width="800"
		height="600"
		onmousemove={handleMouseMove}
		onclick={startGame}
	></canvas>

	<div class="game-status">
		{#if pointerLockElement}
			<p>🎮 Pointer locked to: {pointerLockElement.tagName}</p>
			<p><kbd>Esc</kbd> to release</p>
		{:else}
			<p>Click canvas to capture pointer</p>
		{/if}

		{#if fullscreenElement}
			<p>📺 Fullscreen active</p>
		{/if}
	</div>
</div>

Integrando Attachments com `<svelte:document>`

O Svelte 5.29 introduziu attachments por meio da diretiva {@attach ...} como a forma moderna e totalmente reativa de anexar comportamentos a elementos. Attachments são funções que são executadas em um efeito quando um elemento é montado e podem, opcionalmente, retornar uma função de limpeza. Ao contrário da diretiva legada use: (actions), os attachments são totalmente reativos — eles são executados novamente automaticamente quando qualquer estado lido dentro deles muda.

O elemento especial <svelte:document> suporta tanto a diretiva legada use: quanto a sintaxe moderna {@attach ...}, permitindo encapsular comportamentos reutilizáveis em nível de documento.

Entendendo Attachments vs Actions

Antes de mergulhar no uso em nível de documento, vamos esclarecer a distinção entre essas duas abordagens:

Actions (use:): Executam uma vez quando o elemento é montado. Elas não são executadas novamente automaticamente quando os argumentos mudam (embora possam usar blocos internos de $effect para reatividade). As actions são a abordagem legada, mas continuam sendo suportadas.

Attachments ({@attach ...}): São executados em um contexto de efeito, tornando-os totalmente reativos. Quando o estado lido dentro do attachment muda, o attachment inteiro é executado novamente (a função de limpeza é chamada primeiro e, em seguida, o attachment é executado novamente). Esta é a abordagem recomendada no Svelte 5.29+.

<script>
	let count = $state(0)

	// Action approach (legacy) - does NOT re-run when count changes
	function actionExample(node, initialCount) {
		console.log('Action ran with:', initialCount)
		// Would need internal $effect to react to changes
	}

	// Attachment approach (modern) - automatically re-runs when count changes
	function attachmentExample(node) {
		console.log('Attachment ran with:', count)
		return () => console.log('Attachment cleanup')
	}
</script>

<!-- Legacy action syntax -->
<div use:actionExample={count}></div>

<!-- Modern attachment syntax - fully reactive -->
<div {@attach attachmentExample}></div>

Attachments em Nível de Documento: Detecção de Ociosidade

Um caso de uso poderoso para attachments em nível de documento é implementar detecção de ociosidade que reage a mudanças de configuração:

<script>
	let userIsIdle = $state(false)
	let idleTimeout = $state(10000)
	let lastActivity = $state(new Date())

	/**
	 * Attachment factory for idle detection
	 * @param {number} timeout - Milliseconds before considering user idle
	 * @returns {import('svelte/attachments').Attachment<Document>}
	 */
	function idleTracker(timeout) {
		return (node) => {
			let idleTimer

			function resetTimer() {
				clearTimeout(idleTimer)

				if (userIsIdle) {
					userIsIdle = false
				}
				lastActivity = new Date()

				idleTimer = setTimeout(() => {
					userIsIdle = true
				}, timeout)
			}

			const activityEvents = ['mousedown', 'mousemove', 'keydown', 'scroll', 'touchstart']

			activityEvents.forEach((event) => {
				node.addEventListener(event, resetTimer, { passive: true })
			})

			resetTimer()

			// Cleanup function - runs before re-run or on unmount
			return () => {
				clearTimeout(idleTimer)
				activityEvents.forEach((event) => {
					node.removeEventListener(event, resetTimer)
				})
			}
		}
	}
</script>

<!--
	Because idleTracker(idleTimeout) runs in an effect context,
	changing idleTimeout will automatically tear down and recreate
	the idle tracker with the new timeout value!
-->
<svelte:document {@attach idleTracker(idleTimeout)} />

<div class="idle-demo">
	<header>
		<h2>Reactive Idle Detection</h2>

		<div class={['user-status', userIsIdle && 'idle']}>
			{userIsIdle ? '💤 User Idle' : '✨ User Active'}
		</div>
	</header>

	<div class="controls">
		<label>
			Idle timeout (seconds):
			<input
				type="range"
				min="5"
				max="60"
				bind:value={() => idleTimeout / 1000, (v) => (idleTimeout = v * 1000)}
			/>
			<span>{idleTimeout / 1000}s</span>
		</label>
	</div>

	<p class="last-activity">
		Last activity: {lastActivity.toLocaleTimeString()}
	</p>

	<p class="explanation">
		Try adjusting the timeout slider—the idle tracker automatically reconfigures itself with the new
		value thanks to attachment reactivity!
	</p>
</div>

<style>
	.user-status {
		padding: 0.5rem 1rem;
		border-radius: 0.5rem;
		font-weight: bold;
		background: #d4edda;
		color: #155724;
		transition: all 0.3s ease;
	}

	.user-status.idle {
		background: #fff3cd;
		color: #856404;
	}
</style>

Atalhos de Teclado com Configuração Reativa

Outro padrão poderoso envolve atalhos de teclado que podem ser reconfigurados dinamicamente:

<script>
	let lastShortcut = $state('')
	let showCommandPalette = $state(false)
	let shortcutsEnabled = $state(true)

	/**
	 * Creates an attachment for keyboard shortcut handling
	 * @param {Record<string, (event: KeyboardEvent) => void>} shortcuts
	 * @returns {import('svelte/attachments').Attachment<Document>}
	 */
	function keyboardShortcuts(shortcuts) {
		return (node) => {
			function handleKeydown(event) {
				if (!shortcutsEnabled) return

				const key = []
				if (event.ctrlKey || event.metaKey) key.push('ctrl')
				if (event.shiftKey) key.push('shift')
				if (event.altKey) key.push('alt')
				key.push(event.key.toLowerCase())

				const combo = key.join('+')

				if (shortcuts[combo]) {
					event.preventDefault()
					shortcuts[combo](event)
					lastShortcut = combo
				}
			}

			node.addEventListener('keydown', handleKeydown)

			return () => {
				node.removeEventListener('keydown', handleKeydown)
			}
		}
	}

	// Define shortcuts - changing this object will trigger attachment re-run
	let shortcuts = $derived({
		'ctrl+k': () => (showCommandPalette = !showCommandPalette),
		'ctrl+s': () => console.log('Save triggered'),
		'ctrl+shift+p': () => console.log('Quick actions'),
		escape: () => (showCommandPalette = false)
	})
</script>

<svelte:document {@attach keyboardShortcuts(shortcuts)} />

<div class="shortcuts-demo">
	<header>
		<h2>Keyboard Shortcuts</h2>

		<label class="toggle">
			<input type="checkbox" bind:checked={shortcutsEnabled} />
			Shortcuts {shortcutsEnabled ? 'enabled' : 'disabled'}
		</label>
	</header>

	<section class="shortcuts-list">
		<h3>Available Shortcuts</h3>
		<ul>
			<li><kbd>Ctrl</kbd> + <kbd>K</kbd> — Toggle Command Palette</li>
			<li><kbd>Ctrl</kbd> + <kbd>S</kbd> — Save</li>
			<li><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> — Quick Actions</li>
			<li><kbd>Escape</kbd> — Close dialogs</li>
		</ul>

		{#if lastShortcut}
			<p class="last-shortcut">Last used: <code>{lastShortcut}</code></p>
		{/if}
	</section>

	{#if showCommandPalette}
		<div class="command-palette" role="dialog" aria-label="Command Palette">
			<input type="text" placeholder="Type a command..." autofocus />
			<p class="hint">Press <kbd>Escape</kbd> to close</p>
		</div>
	{/if}
</div>

<style>
	.command-palette {
		position: fixed;
		top: 20%;
		left: 50%;
		transform: translateX(-50%);
		background: white;
		padding: 1.5rem;
		border-radius: 0.5rem;
		box-shadow: 0 10px 40px rgba(0, 0, 0, 0.2);
		z-index: 1000;
	}

	.command-palette input {
		width: 300px;
		padding: 0.75rem;
		font-size: 1rem;
		border: 1px solid #ddd;
		border-radius: 0.25rem;
	}

	kbd {
		background: #eee;
		padding: 0.2rem 0.4rem;
		border-radius: 0.25rem;
		font-family: monospace;
		font-size: 0.9em;
	}
</style>

Attachments Inline para Comportamento em Nível de Documento

Para casos mais simples, você pode definir attachments inline diretamente no <svelte:document>:

<script>
	let documentClickCount = $state(0)
	let lastClickTarget = $state('')
</script>

<svelte:document
	{@attach (doc) => {
		function handleClick(event) {
			documentClickCount++
			lastClickTarget = event.target?.tagName || 'unknown'
		}

		doc.addEventListener('click', handleClick)

		return () => {
			doc.removeEventListener('click', handleClick)
		}
	}}
/>

<div class="click-tracker">
	<p>Document clicks: {documentClickCount}</p>
	<p>Last clicked element: <code>{lastClickTarget || 'none'}</code></p>
</div>

Controlando Re-execuções de Attachments

Como os attachments são totalmente reativos, eles são executados novamente sempre que qualquer estado lido dentro deles muda. Para operações de configuração custosas, talvez você queira isolar as partes reativas em um efeito aninhado:

<script>
	let config = $state({ threshold: 100, debug: false })

	/**
	 * Attachment with expensive setup that shouldn't re-run on every config change
	 * @returns {import('svelte/attachments').Attachment<Document>}
	 */
	function expensiveDocumentBehavior() {
		return (node) => {
			// Expensive setup - only runs once per mount
			console.log('Expensive setup work...')
			const observer = new IntersectionObserver(() => {})

			// Reactive part - runs when config changes
			$effect(() => {
				console.log('Config changed:', config.threshold, config.debug)
				// React to config changes without re-running expensive setup
			})

			return () => {
				observer.disconnect()
			}
		}
	}
</script>

<svelte:document {@attach expensiveDocumentBehavior()} />

Convertendo Actions Legadas para Attachments

Se você estiver usando bibliotecas de terceiros que fornecem actions, pode convertê-las para attachments usando o utilitário fromAction de svelte/attachments:

<script>
	import { fromAction } from 'svelte/attachments'
	import { someLibraryAction } from 'some-library'

	// Convert the action to an attachment
	const attachableVersion = fromAction(someLibraryAction)
</script>

<!-- Now usable with {@attach ...} syntax -->
<svelte:document {@attach attachableVersion(options)} />

Coordenando Múltiplos Elementos Especiais

Aplicações do mundo real frequentemente precisam coordenar eventos de documento, janela e body juntos. Entender como esses três elementos especiais diferem ajuda você a escolher a ferramenta certa para cada situação:

<script>
	// Window-specific: scroll position, resize, online/offline
	let scrollY = $state(0)
	let innerWidth = $state(0)
	let online = $state(true)

	// Document-specific: visibility, active element, fullscreen
	let visibilityState = $state('visible')
	let activeElement = $state(null)

	// Body-specific: mouse enter/leave the viewport
	let mouseInViewport = $state(true)

	// Derived state combining multiple sources
	let userEngagement = $derived.by(() => {
		if (visibilityState === 'hidden') return 'away'
		if (!mouseInViewport) return 'distracted'
		if (!activeElement || activeElement === document.body) return 'passive'
		return 'engaged'
	})

	$effect(() => {
		console.log(`User engagement level: ${userEngagement}`)

		if (userEngagement === 'away') {
			// Pause expensive operations
		} else if (userEngagement === 'engaged') {
			// Full operation mode
		}
	})
</script>

<!-- Window bindings for viewport and network state -->
<svelte:window bind:scrollY bind:innerWidth bind:online />

<!-- Document bindings for page-level state -->
<svelte:document bind:visibilityState bind:activeElement />

<!-- Body events for mouse presence detection -->
<svelte:body
	onmouseenter={() => (mouseInViewport = true)}
	onmouseleave={() => (mouseInViewport = false)}
/>

<div class="engagement-dashboard">
	<h2>User Engagement Monitor</h2>

	<div class="metrics-grid">
		<div class="metric">
			<span class="label">Engagement</span>
			<span class="value" data-level={userEngagement}>{userEngagement}</span>
		</div>

		<div class="metric">
			<span class="label">Page Visible</span>
			<span class="value">{visibilityState === 'visible' ? '✓' : '✗'}</span>
		</div>

		<div class="metric">
			<span class="label">Mouse in Viewport</span>
			<span class="value">{mouseInViewport ? '✓' : '✗'}</span>
		</div>

		<div class="metric">
			<span class="label">Network</span>
			<span class="value">{online ? 'Online' : 'Offline'}</span>
		</div>

		<div class="metric">
			<span class="label">Scroll Position</span>
			<span class="value">{Math.round(scrollY)}px</span>
		</div>

		<div class="metric">
			<span class="label">Viewport Width</span>
			<span class="value">{innerWidth}px</span>
		</div>
	</div>
</div>

Considerações sobre Renderização no Servidor

Os elementos especiais do Svelte são projetados com segurança para SSR em mente. O elemento <svelte:document> compila para código que é executado apenas em ambientes de navegador, evitando erros de "document is not defined" durante a renderização no servidor.

No entanto, você ainda deve ter cuidado com o código no seu bloco <script> que faz referência a globais do navegador:

<script>
	// DANGEROUS: This runs during SSR and will crash
	// const state = document.visibilityState;

	// SAFE: Initialize with a sensible default
	let visibilityState = $state('visible')

	// SAFE: Use $effect for browser-only code
	$effect(() => {
		// This only runs in the browser after mount
		visibilityState = document.visibilityState
	})

	// SAFE: Check for browser environment explicitly
	function checkDocumentState() {
		if (typeof document === 'undefined') return
		// Safe to access document here
	}
</script>

<svelte:document bind:visibilityState />

O binding em si lida com o caso de SSR de forma elegante — bind:visibilityState não causará erros durante a renderização no servidor. Mas qualquer código imperativo que acesse document diretamente precisa de proteção.

Para aplicações SvelteKit, use a verificação browser de $app/environment:

<script>
	import { browser } from '$app/environment'

	let activeElement = $state(null)
	let documentTitle = $state('')

	$effect(() => {
		if (!browser) return

		documentTitle = document.title

		const observer = new MutationObserver(() => {
			documentTitle = document.title
		})

		const titleElement = document.querySelector('title')
		if (titleElement) {
			observer.observe(titleElement, { childList: true })
		}

		return () => observer.disconnect()
	})
</script>

<svelte:document bind:activeElement />

<div>
	<p>Current page title: {documentTitle}</p>
	<p>Active element: {activeElement?.tagName || 'None'}</p>
</div>

Padrão Avançado: Construindo uma Armadilha de Foco

A captura de foco é essencial para diálogos modais acessíveis. Usando <svelte:document> combinado com o binding activeElement, podemos construir uma armadilha de foco robusta:

<script>
	let activeElement = $state(null)
	let trapContainer = $state(null)
	let isTrapping = $state(false)
	let previousActiveElement = null

	export function activate(container) {
		trapContainer = container
		isTrapping = true
		previousActiveElement = activeElement

		const firstFocusable = getFirstFocusable(container)
		firstFocusable?.focus()
	}

	export function deactivate() {
		isTrapping = false
		trapContainer = null

		previousActiveElement?.focus()
		previousActiveElement = null
	}

	function getFirstFocusable(container) {
		return container?.querySelector(
			'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
		)
	}

	function getAllFocusable(container) {
		return Array.from(
			container?.querySelectorAll(
				'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
			) || []
		)
	}

	function handleKeydown(event) {
		if (!isTrapping || !trapContainer) return

		if (event.key === 'Tab') {
			const focusable = getAllFocusable(trapContainer)
			const firstFocusable = focusable[0]
			const lastFocusable = focusable[focusable.length - 1]

			if (event.shiftKey && activeElement === firstFocusable) {
				event.preventDefault()
				lastFocusable?.focus()
			} else if (!event.shiftKey && activeElement === lastFocusable) {
				event.preventDefault()
				firstFocusable?.focus()
			}
		}

		if (event.key === 'Escape') {
			deactivate()
		}
	}

	// Guard against focus leaving the trap
	$effect(() => {
		if (!isTrapping || !trapContainer || !activeElement) return

		if (!trapContainer.contains(activeElement)) {
			const firstFocusable = getFirstFocusable(trapContainer)
			firstFocusable?.focus()
		}
	})
</script>

<svelte:document bind:activeElement onkeydown={handleKeydown} />

Armadilhas Comuns e Como Evitá-las

1. Esquecer que Bindings São Somente Leitura

Todos os bindings de <svelte:document> são somente leitura. Tentar defini-los programaticamente não funcionará:

<script>
	let activeElement = $state(null)

	function focusSpecificElement() {
		// THIS DOESN'T WORK - activeElement binding is readonly
		// activeElement = document.getElementById('target');

		// PREFERRED:Instead, focus the element directly
		document.getElementById('target')?.focus()
		// The binding will automatically update to reflect the new focus
	}
</script>

<svelte:document bind:activeElement />

2. Criando Vazamentos de Memória com Effects

Ao usar $effect para responder a mudanças de estado do documento, sempre retorne funções de limpeza para quaisquer recursos que você criar:

<script>
	let visibilityState = $state('visible')

	// AVOID: MEMORY LEAK: Interval never cleaned up
	$effect(() => {
		if (visibilityState === 'visible') {
			setInterval(() => console.log('tick'), 1000)
		}
	})

	// PREFERRED: Return cleanup function
	$effect(() => {
		if (visibilityState === 'visible') {
			const interval = setInterval(() => console.log('tick'), 1000)
			return () => clearInterval(interval)
		}
	})
</script>

<svelte:document bind:visibilityState />

3. Attachment Re-executando com Frequência Excessiva

Attachments são re-executados sempre que qualquer estado lido dentro deles é alterado. Esteja atento ao estado que você acessa:

<script>
	let config = $state({ timeout: 5000, label: 'test' });

	// AVOID PROBLEM: Re-runs on ANY config property change, even label
	function problematicAttachment() {
		return (node) => {
			console.log('Setup with timeout:', config.timeout);
			// Reading config.timeout makes attachment dependent on entire config object
			return () => console.log('Cleanup');
		};
	}

	// PREFERRED: Pass only what you need
	function betterAttachment(timeout) {
		return (node) => {
			console.log('Setup with timeout:', timeout);
			return () => console.log('Cleanup');
		};
	}
</script>

<!-- Re-runs on any config change -->
<svelte:document {@attach problematicAttachment()} />

<!-- Only re-runs when timeout changes -->
<svelte:document {@attach betterAttachment(config.timeout)} />

4. Dependência Excessiva de Eventos do Document

Alguns eventos para os quais você pode esperar precisar de <svelte:document> funcionam bem com <svelte:window> ou elementos regulares. Use o alvo mais específico possível:

<!-- AVOID: Overkill: keydown events bubble, use svelte:window or element instead -->
<svelte:document onkeydown={handleKeydown} />

<!-- PREFERRED: svelte:window for global keyboard shortcuts -->
<svelte:window onkeydown={handleKeydown} />

<!-- BEST: Element-level for scoped keyboard handling -->
<div onkeydown={handleKeydown} tabindex="0">
	<!-- content -->
</div>

Reserve <svelte:document> para eventos que realmente só disparam no objeto document: visibilitychange, selectionchange, fullscreenchange e eventos similares específicos do document.

5. Não Tratar o Estado Inicial

Os bindings do document podem não ter seus valores esperados imediatamente na montagem do componente. Projete sua lógica para tratar estados indefinidos ou iniciais de forma adequada:

<script>
	let activeElement = $state(null)

	// AVOID FRAGILE: Assumes activeElement is always defined
	$effect(() => {
		console.log(activeElement.tagName) // May throw!
	})

	// PREFERRED ROBUST: Guard against null/undefined
	$effect(() => {
		if (activeElement) {
			console.log(activeElement.tagName)
		}
	})
</script>

<svelte:document bind:activeElement />

Resumo das Melhores Práticas

Ao trabalhar com <svelte:document> no Svelte 5, tenha estes princípios em mente:

Use <svelte:document> especificamente para preocupações de nível de document. Eventos como visibilitychange, selectionchange e fullscreenchange disparam apenas no document. Propriedades como activeElement e visibilityState existem apenas no document. Não o utilize para eventos que poderiam ser tratados em um nível mais específico.

Prefira attachments ({@attach ...}) em vez de actions (use:) para novo código. Attachments fornecem reatividade completa pronta para uso e se integram melhor com o modelo reativo do Svelte 5. Use fromAction de svelte/attachments para converter actions legadas quando necessário.

Combine bindings declarativos com $effect para padrões reativos poderosos. O binding fornece acesso reativo ao estado do document; effects permitem que você responda a esse estado com efeitos colaterais, limpeza e lógica complexa.

Lembre-se da segurança para SSR. Embora o próprio <svelte:document> trate SSR de forma adequada, qualquer código imperativo no seu bloco de script que acessa document diretamente precisa de proteção via effects ou verificações de ambiente.

Esteja atento à reatividade de attachment. Attachments são re-executados quando qualquer estado lido dentro deles é alterado. Passe apenas os valores específicos necessários, ou use effects aninhados para operações de configuração custosas que não devem ser re-executadas.

Coordene com <svelte:window> e <svelte:body> de forma ponderada. Cada elemento especial serve a um propósito distinto na hierarquia do DOM. Entender quais eventos e propriedades pertencem a cada um ajuda você a construir componentes mais limpos e de fácil manutenção.

Conclusão

O elemento especial <svelte:document> representa o compromisso do Svelte em tornar as APIs do DOM acessíveis de forma reativa e declarativa, enquanto lida com a complexidade do gerenciamento de ciclo de vida, compatibilidade com SSR e limpeza automática. Ao fazer a ponte entre as APIs imperativas do navegador e o modelo de componente reativo do Svelte, ele possibilita interações sofisticadas — desde otimização de desempenho com consciência de visibilidade até recursos de edição colaborativa — sem sacrificar a experiência do desenvolvedor ou a manutenibilidade do código.

Dominar o <svelte:document> requer entender não apenas sua sintaxe, mas o contexto mais amplo de como documents, windows e bodies interagem no modelo de eventos do navegador. A introdução de attachments no Svelte 5.29 aprimora ainda mais o poder deste elemento, fornecendo reatividade completa e composabilidade para interações em nível de document.

À medida que você constrói aplicações cada vez mais sofisticadas, os padrões explorados aqui — rastreamento de visibilidade, gerenciamento de foco, coordenação de tela cheia e reatividade baseada em attachment — serão inestimáveis para criar aplicações que respondem de forma inteligente à presença do usuário e às mudanças de estado do document.

Principais Conclusões

<svelte:document> fornece acesso declarativo a eventos e propriedades de nível de document com segurança automática para SSR, tratando eventos como visibilitychange, selectionchange, fullscreenchange e propriedades como activeElement, visibilityState
Bindings reativos habilitam fluxo de dados bidirecional com propriedades somente leitura (activeElement, pointerLockElement, fullscreenElement, visibilityState, pictureInPictureElement) fornecendo o estado atual do document
Attachments ({@attach}) são preferidos em relação a actions no Svelte 5.29+, oferecendo reatividade completa, composabilidade, suporte inline e melhor integração com TypeScript em comparação à sintaxe legada use:
O rastreamento de visibilidade otimiza desempenho e UX pausando animações, adiando atualizações e gerenciando operações de uso intensivo de recursos quando os usuários alternam abas ou minimizam janelas
A detecção de mudança de seleção habilita recursos de edição colaborativa como sincronização de posição do cursor, barras de ferramentas de formatação de texto e encadeamento de comentários em tempo real
As APIs de tela cheia e pointer lock requerem gestos do usuário, o que significa que requestFullscreen() ou requestPointerLock() programáticos devem ser acionados por cliques de botão ou outras interações do usuário
Combinar $derived com bindings do document cria padrões reativos que respondem automaticamente a mudanças de estado sem gerenciamento manual de effects ou atualizações de manipuladores de eventos
A segurança para SSR é integrada no próprio <svelte:document>, mas o acesso imperativo a document em blocos de script requer encapsulamento em $effect ou verificações de ambiente (typeof document !== 'undefined')

Veja Também

Documentação Oficial do Svelte 5 - <svelte:document>
MDN Web Docs - Interface Document
API de Visibilidade de Página - Entendendo estados de visibilidade e otimização de desempenho
API Fullscreen - Guia completo para o modo de tela cheia e requisitos de gesto do usuário
API Pointer Lock - Controles em primeira pessoa e movimento irrestrito do mouse
API Selection - Trabalhando com seleção de texto e intervalos em documents