Entendiendo el Contexto del Modelo de Objetos del Documento

Antes de profundizar en la mecánica de svelte:document, es fundamental comprender por qué existe este elemento especial y qué espacio de problemas ocupa dentro de la arquitectura de Svelte. El Modelo de Objetos del Documento del navegador presenta una estructura jerárquica donde el objeto document se encuentra como el nodo raíz que contiene todo el contenido de la página, distinto del objeto window (que representa la ventana del navegador en sí) y el elemento body (el contenedor visible del contenido de la página).

Muchos eventos del navegador se propagan hacia arriba a través de esta jerarquía, pero ciertos eventos se disparan específicamente en el objeto document y nunca alcanzan el window. El evento visibilitychange representa el ejemplo más común: este evento se dispara exclusivamente en document cuando los usuarios cambian de pestaña, minimizan los navegadores o navegan a otro lugar. De manera similar, propiedades como activeElement (que rastrea qué elemento tiene el foco actualmente) existen solo en document, haciendo necesario el acceso directo al documento para ciertos comportamientos de la aplicación.

El elemento especial <svelte:document> de Svelte proporciona acceso declarativo a esta funcionalidad a nivel de documento mientras mantiene los principios de Svelte de limpieza automática, seguridad en el renderizado del lado del servidor y soporte de binding reactivo. Sin esta abstracción, los desarrolladores necesitarían conectar manualmente los listeners de eventos en los hooks del ciclo de vida, recordar limpiarlos al destruir el componente y manejar los entornos SSR donde document no existe.

Sintaxis Básica y Requisitos de Ubicación

El elemento <svelte:document> sigue una regla estricta de ubicación compartida con sus elementos especiales hermanos <svelte:window> y <svelte:body>: debe aparecer en el nivel superior de tu componente, nunca anidado dentro de bloques, elementos o estructuras condicionales.

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

Intentar colocar <svelte:document> dentro de bloques condicionales o elementos provocará un error del compilador. Esta restricción existe porque Svelte necesita registrar los listeners a nivel de documento durante la inicialización del componente, no condicionalmente durante el renderizado. El compilador aplica esto para evitar comportamientos confusos en tiempo de ejecución donde los listeners pueden o no existir según las condiciones de renderizado.

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

La razón detrás de esta restricción se conecta con la estrategia de compilación de Svelte. Los elementos especiales como <svelte:document> se compilan en llamadas directas a la API del DOM durante la inicialización del componente. Colocarlos dentro de bloques condicionales requeriría una gestión dinámica de listeners con una coordinación compleja del ciclo de vida, lo que anularía la simplicidad que hace valiosos a estos elementos.

Manejo de Eventos en el Documento

El caso de uso principal de <svelte:document> implica escuchar eventos específicos del documento. Svelte 5 utiliza la sintaxis moderna oneventname en lugar de la directiva heredada on:eventname, alineándose con los patrones nativos del DOM y mejorando el rendimiento mediante la delegación de eventos.

El Evento visibilitychange

El evento visibilitychange representa el ejemplo canónico de uso de <svelte:document>. Este evento se dispara cada vez que cambia el estado de visibilidad de la página: cuando los usuarios cambian de pestaña del navegador, minimizan ventanas o navegan a otras aplicaciones.

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

Este patrón resulta invaluable para aplicaciones que necesitan pausar operaciones costosas cuando los usuarios se alejan. Los reproductores de video pueden pausar la reproducción, los sistemas de analítica pueden rastrear el tiempo de interacción con precisión, y las aplicaciones en tiempo real pueden reducir el polling al servidor cuando la página no está visible.

Eventos de Selección y Portapapeles

El objeto document sirve como destino para varios eventos relacionados con la selección y el portapapeles que no se propagan hasta 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 Pantalla Completa

Gestionar el estado de pantalla completa requiere manejo de eventos a nivel de documento, ya que los eventos fullscreenchange y fullscreenerror se disparan en 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 Reactivos: Leyendo el Estado del Documento

Más allá del manejo de eventos, <svelte:document> proporciona bindings reactivos a cuatro propiedades del documento. A diferencia de muchos bindings de elementos en Svelte, todos los bindings de documento son de solo lectura: puedes observar sus valores pero no puedes establecerlos programáticamente mediante binding.

Binding activeElement

La propiedad activeElement rastrea qué elemento del DOM tiene el foco actualmente. Este binding se actualiza de forma reactiva cuando los usuarios navegan por campos de formulario con Tab, hacen clic en elementos interactivos o cuando el foco se mueve programáticamente:

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

El binding activeElement permite patrones sofisticados de gestión del foco, mejoras de accesibilidad y sistemas de navegación por teclado. Es particularmente valioso para diálogos modales que necesitan atrapar el foco, implementaciones de skip-link y validación de formularios complejos que responde al foco de los campos.

Binding visibilityState

Mientras que el evento visibilitychange te indica cuándo cambia la visibilidad, el binding visibilityState te da acceso reactivo al estado actual:

<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 y pointerLockElement

Estos bindings proporcionan acceso reactivo al elemento actual en pantalla completa y a cualquier elemento que haya capturado el bloqueo del puntero:

<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 con `<svelte:document>`

Svelte 5.29 introdujo los attachments mediante la directiva {@attach ...} como la forma moderna y completamente reactiva de adjuntar comportamientos a los elementos. Los attachments son funciones que se ejecutan en un efecto cuando un elemento se monta y pueden retornar opcionalmente una función de limpieza. A diferencia de la directiva use: más antigua (acciones), los attachments son completamente reactivos: se vuelven a ejecutar automáticamente cuando cambia cualquier estado leído dentro de ellos.

El elemento especial <svelte:document> admite tanto la directiva heredada use: como la sintaxis moderna {@attach ...}, lo que te permite encapsular comportamientos reutilizables a nivel de documento.

Entendiendo Attachments vs Acciones

Antes de profundizar en el uso a nivel de documento, aclaremos la distinción entre estos dos enfoques:

Acciones (use:): Se ejecutan una vez cuando el elemento se monta. No se vuelven a ejecutar automáticamente cuando cambian los argumentos (aunque pueden usar bloques internos $effect para la reactividad). Las acciones son el enfoque heredado pero siguen siendo compatibles.

Attachments ({@attach ...}): Se ejecutan en un contexto de efecto, haciéndolos completamente reactivos. Cuando el estado leído dentro del attachment cambia, el attachment completo se vuelve a ejecutar (primero se llama a la función de limpieza, luego el attachment se ejecuta nuevamente). Este es el enfoque recomendado en 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 a Nivel de Documento: Detección de Inactividad

Un caso de uso poderoso para los attachments a nivel de documento es implementar la detección de inactividad que reacciona a cambios de configuración:

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

Atajos de Teclado con Configuración Reactiva

Otro patrón poderoso involucra atajos de teclado que pueden reconfigurarse dinámicamente:

<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 en Línea para Comportamiento a Nivel de Documento

Para casos más simples, puedes definir attachments en línea directamente en <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 la Re-ejecución de Attachments

Dado que los attachments son completamente reactivos, se vuelven a ejecutar cada vez que cambia cualquier estado leído dentro de ellos. Para operaciones de configuración costosas, es posible que quieras aislar las partes reactivas en un efecto anidado:

<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()} />

Convirtiendo Acciones Heredadas a Attachments

Si estás usando bibliotecas de terceros que proporcionan acciones, puedes convertirlas a attachments usando la utilidad 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)} />

Coordinando Múltiples Elementos Especiales

Las aplicaciones del mundo real frecuentemente necesitan coordinar eventos de document, window y body juntos. Entender cómo difieren estos tres elementos especiales te ayuda a elegir la herramienta correcta para cada situación:

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

Consideraciones sobre el Renderizado del Lado del Servidor

Los elementos especiales de Svelte están diseñados con la seguridad SSR en mente. El elemento <svelte:document> se compila en código que solo se ejecuta en entornos de navegador, evitando errores de "document is not defined" durante el renderizado en el servidor.

Sin embargo, aún debes tener cuidado con el código en tu bloque <script> que hace referencia a variables globales del 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 />

El binding en sí maneja el caso SSR de forma elegante: bind:visibilityState no causará errores durante el renderizado en el servidor. Pero cualquier código imperativo que acceda a document directamente necesita protección.

Para aplicaciones SvelteKit, usa la verificación 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>

Patrón Avanzado: Construir una Trampa de Foco

La trampa de foco es esencial para los diálogos modales accesibles. Usando <svelte:document> combinado con el binding activeElement, podemos construir una trampa 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} />

Errores Comunes y Cómo Evitarlos

1. Olvidar que los Bindings Son de Solo Lectura

Todos los bindings de <svelte:document> son de solo lectura. Intentar establecerlos programáticamente no 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. Crear Fugas de Memoria con Effects

Al usar $effect para responder a cambios en el estado del documento, siempre retorna funciones de limpieza para cualquier recurso que crees:

<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. Los Attachments Se Re-ejecutan con Demasiada Frecuencia

Los attachments se re-ejecutan cada vez que cambia cualquier estado leído dentro de ellos. Ten en cuenta qué estado accedes:

<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. Depender Demasiado de los Eventos del Documento

Algunos eventos para los que podrías pensar que necesitas <svelte:document> funcionan bien en <svelte:window> o en elementos regulares. Usa el objetivo más específico posible:

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

Reserva <svelte:document> para eventos que verdaderamente solo se disparan en el objeto document: visibilitychange, selectionchange, fullscreenchange y eventos similares específicos del documento.

5. No Manejar el Estado Inicial

Los bindings del documento pueden no tener sus valores esperados inmediatamente al montar el componente. Diseña tu lógica para manejar los estados indefinidos o iniciales de forma adecuada:

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

Resumen de Mejores Prácticas

Al trabajar con <svelte:document> en Svelte 5, ten en cuenta estos principios:

Usa <svelte:document> específicamente para cuestiones a nivel de documento. Eventos como visibilitychange, selectionchange y fullscreenchange solo se disparan en el documento. Propiedades como activeElement y visibilityState existen únicamente en el documento. No lo uses para eventos que podrían manejarse en un nivel más específico.

Prefiere los attachments ({@attach ...}) sobre las actions (use:) en el código nuevo. Los attachments proporcionan reactividad completa de fábrica y se integran mejor con el modelo reactivo de Svelte 5. Usa fromAction de svelte/attachments para convertir actions heredadas cuando sea necesario.

Combina bindings declarativos con $effect para patrones reactivos potentes. El binding te da acceso reactivo al estado del documento; los effects te permiten responder a ese estado con efectos secundarios, limpieza y lógica compleja.

Recuerda la seguridad en SSR. Si bien <svelte:document> por sí mismo maneja el SSR de forma adecuada, cualquier código imperativo en tu bloque de script que acceda directamente a document necesita protección mediante effects o verificaciones de entorno.

Ten en cuenta la reactividad de los attachments. Los attachments se re-ejecutan cuando cambia cualquier estado leído dentro de ellos. Pasa solo los valores específicos necesarios, o usa effects anidados para operaciones de configuración costosas que no deberían re-ejecutarse.

Coordina con <svelte:window> y <svelte:body> de forma reflexiva. Cada elemento especial cumple un propósito distinto en la jerarquía del DOM. Entender a qué eventos y propiedades pertenece cada uno te ayuda a construir componentes más limpios y fáciles de mantener.

Conclusión

El elemento especial <svelte:document> representa el compromiso de Svelte de hacer accesibles las APIs del DOM de manera reactiva y declarativa, mientras gestiona la complejidad del ciclo de vida, la compatibilidad con SSR y la limpieza automática. Al cerrar la brecha entre las APIs imperativas del navegador y el modelo de componentes reactivo de Svelte, permite interacciones sofisticadas —desde la optimización del rendimiento según la visibilidad hasta funciones de edición colaborativa— sin sacrificar la experiencia del desarrollador ni la mantenibilidad del código.

Dominar <svelte:document> requiere comprender no solo su sintaxis, sino el contexto más amplio de cómo los documentos, ventanas y cuerpos interactúan en el modelo de eventos del navegador. La introducción de los attachments en Svelte 5.29 potencia aún más este elemento, proporcionando reactividad completa y composabilidad para las interacciones a nivel de documento.

A medida que construyas aplicaciones cada vez más sofisticadas, los patrones explorados aquí —seguimiento de visibilidad, gestión del foco, coordinación de pantalla completa y reactividad basada en attachments— serán invaluables para crear aplicaciones que respondan inteligentemente a la presencia del usuario y a los cambios en el estado del documento.

Puntos Clave

<svelte:document> proporciona acceso declarativo a eventos y propiedades a nivel de documento con seguridad automática en SSR, manejando eventos como visibilitychange, selectionchange, fullscreenchange y propiedades como activeElement, visibilityState
Los bindings reactivos permiten el flujo de datos bidireccional con propiedades de solo lectura (activeElement, pointerLockElement, fullscreenElement, visibilityState, pictureInPictureElement) que proporcionan el estado actual del documento
Los attachments ({@attach}) son preferidos sobre las actions en Svelte 5.29+, ofreciendo reactividad completa, composabilidad, soporte en línea y mejor integración con TypeScript en comparación con la sintaxis heredada use:
El seguimiento de visibilidad optimiza el rendimiento y la UX pausando animaciones, aplazando actualizaciones y gestionando operaciones que consumen muchos recursos cuando los usuarios cambian de pestaña o minimizan ventanas
La detección de cambios de selección permite funciones de edición colaborativa como sincronización de la posición del cursor, barras de herramientas de formato de texto e hilos de comentarios en tiempo real
Las APIs de pantalla completa y bloqueo del puntero requieren gestos del usuario, lo que significa que requestFullscreen() o requestPointerLock() programáticos deben ser activados por clics de botón u otras interacciones del usuario
Combinar $derived con bindings del documento crea patrones reactivos que responden automáticamente a los cambios de estado sin gestión manual de effects ni actualizaciones de manejadores de eventos
La seguridad en SSR está integrada para <svelte:document> en sí mismo, pero el acceso imperativo a document en bloques de script requiere envoltura con $effect o verificaciones de entorno (typeof document !== 'undefined')

Ver También

Documentación Oficial de Svelte 5 - <svelte:document>
MDN Web Docs - Interfaz Document
API de Visibilidad de Página - Comprensión de los estados de visibilidad y la optimización del rendimiento
API de Pantalla Completa - Guía completa del modo de pantalla completa y los requisitos de gestos del usuario
API de Bloqueo del Puntero - Controles en primera persona y movimiento irrestricto del mouse
API de Selección - Trabajo con selección de texto y rangos en documentos