La Guía Completa para el Manejo de Eventos en Svelte

Los eventos son la forma en que tu aplicación responde a la interacción del usuario: clics, pulsaciones de teclas, toques, envíos de formularios. Svelte 5 maneja los eventos a través de atributos de elemento, lo que los hace consistentes con la forma en que estableces otras propiedades. Esta guía cubre todo, desde manejadores de clic básicos hasta patrones complejos como la trampa de foco y el manejo de gestos.

Atributos de Eventos: Lo Básico

Svelte 5 usa atributos de eventos HTML estándar: onclick, onkeydown, onsubmit, onmousemove; cuando asignas una función a ellos, esa función se llama cada vez que el evento ocurre en ese elemento.

<script>
	let count = $state(0)

	function handleClick() {
		count++
	}
</script>

<button onclick={handleClick}>
	Clicked {count} times
</button>

Para operaciones simples, las funciones de flecha en línea funcionan bien y no tienen penalización de rendimiento en Svelte:

<button onclick={() => count++}>
	Clicked {count} times
</button>

Funciones con Nombre vs. Manejadores en Línea

Usa funciones con nombre cuando tu manejador tiene múltiples pasos, necesita un nombre descriptivo para mejorar la legibilidad, o será reutilizado:

<script>
	let items = $state([])

	function handleSubmit(event) {
		event.preventDefault()
		const formData = new FormData(event.target)
		const newItem = formData.get('item')

		if (newItem.trim()) {
			items = [...items, newItem.trim()]
			event.target.reset()
		}
	}
</script>

<form onsubmit={handleSubmit}>
	<input name="item" placeholder="Add item" />
	<button type="submit">Add</button>
</form>

Usa manejadores en línea para acciones simples de un solo propósito donde una función con nombre sería innecesaria:

<button onclick={() => (showModal = true)}>Open</button>
<button onclick={() => (items = [])}>Clear All</button>

Trabajando con el Objeto de Evento

Cuando se dispara un evento, el navegador crea un objeto de evento que contiene información sobre lo que ocurrió. Svelte pasa este objeto a tu función manejadora automáticamente.

<script>
	function handleClick(event) {
		console.log('Event type:', event.type) // "click"
		console.log('Target element:', event.target) // The clicked element
		console.log('Mouse position:', event.clientX, event.clientY)
		console.log('Shift held:', event.shiftKey)
	}
</script>

<button onclick={handleClick}>Click me</button>

Pasar Datos Personalizados a los Manejadores

Con frecuencia necesitas pasar datos adicionales a tu manejador, como qué elemento de una lista fue clicado. Envuelve tu manejador en una función de flecha para capturar esos datos:

<script>
	let tasks = $state([
		{ id: 1, text: 'Learn Svelte' },
		{ id: 2, text: 'Build something' },
		{ id: 3, text: 'Ship it' }
	])

	function deleteTask(taskId) {
		tasks = tasks.filter((t) => t.id !== taskId)
	}
</script>

<ul>
	{#each tasks as task}
		<li>
			{task.text}
			<button onclick={() => deleteTask(task.id)}>Delete</button>
		</li>
	{/each}
</ul>

La función de flecha crea un closure que captura el task.id específico para cada elemento de la lista. Al hacer clic, llama a deleteTask con ese ID.

Si necesitas tanto el objeto de evento COMO datos personalizados:

<script>
	function handleAction(taskId, event) {
		console.log('Task:', taskId)
		console.log('Clicked at:', event.clientX, event.clientY)
	}
</script>

<button onclick={(e) => handleAction(task.id, e)}>Action</button>

Propiedades Clave de los Eventos por Tipo

Los eventos de ratón incluyen clientX/clientY (coordenadas del viewport), pageX/pageY (coordenadas del documento), button (qué botón: 0=izquierdo, 1=medio, 2=derecho) y estados de teclas modificadoras (shiftKey, ctrlKey, altKey, metaKey).

Los eventos de teclado incluyen key (el valor de la tecla como "Enter", "a", "ArrowDown"), code (tecla física como "KeyA" independientemente del diseño) y repeat (verdadero si la tecla se mantiene presionada).

Los eventos de formulario te dan event.target como el elemento del formulario, que puedes pasar a FormData o acceder a campos individuales mediante event.target.elements.

Propagación de Eventos y Delegación

Cuando haces clic en un botón dentro de un div, ambos elementos pueden potencialmente manejar ese clic. El navegador envía los eventos a través de tres fases:

Fase de captura: El evento viaja HACIA ABAJO desde window hasta el objetivo
Fase de objetivo: El evento llega al elemento que fue realmente clicado
Fase de burbuja: El evento viaja de regreso HACIA ARRIBA desde el objetivo hasta window

Por defecto, los manejadores se disparan durante la fase de burbuja. Esto significa que un clic en un elemento anidado burbujeará hacia arriba y disparará los manejadores en los elementos padre también.

Target vs. CurrentTarget

Esta distinción importa cuando adjuntas un manejador a un contenedor pero los usuarios hacen clic en elementos hijos dentro de él:

<script>
	function handleContainerClick(event) {
		// event.target = the actual element clicked (could be p, button, or the div)
		// event.currentTarget = the element with the handler (always the div)
		console.log('Clicked on:', event.target.tagName)
		console.log('Handler on:', event.currentTarget.tagName)
	}
</script>

<div onclick={handleContainerClick}>
	<p>Click this paragraph</p>
	<button>Or this button</button>
</div>

Clic en el párrafo: target es P, currentTarget es DIV. Clic en el botón: target es BUTTON, currentTarget es DIV.

Delegación de Eventos en Svelte

Svelte usa delegación de eventos para eventos comunes como click, input, keydown y muchos otros. En lugar de adjuntar un listener a cada elemento, Svelte adjunta un único listener en la raíz del documento y enruta los eventos a los manejadores apropiados.

Esto ocurre de forma automática y transparente: escribes los manejadores normalmente y Svelte optimiza detrás de escena. Los beneficios son significativos: menor uso de memoria, mejor rendimiento con contenido dinámico y sin necesidad de limpieza manual.

Sin embargo, hay implicaciones que debes entender:

Los eventos personalizados deben burbujear. Si dispateas eventos personalizados manualmente, incluye bubbles: true o la delegación de Svelte no los capturará:

// This won't reach Svelte's delegated handlers
element.dispatchEvent(new CustomEvent('myevent'))

// This will work correctly
element.dispatchEvent(new CustomEvent('myevent', { bubbles: true }))

Detener la propagación puede romper cosas. Si agregas un addEventListener manual y llamas a stopPropagation(), el evento no llegará al listener raíz de Svelte. Usa la función on de svelte/events si necesitas listeners manuales que se integren con la delegación de Svelte.

Manejadores de Fase de Captura

Para manejar eventos durante la fase de captura (antes de que lleguen al objetivo), agrega capture al nombre del evento:

<script>
	function handleCapture(event) {
		console.log('Capture: traveling down to', event.target.tagName)
	}

	function handleBubble(event) {
		console.log('Bubble: traveling up from', event.target.tagName)
	}
</script>

<div onclickcapture={handleCapture} onclick={handleBubble}>
	<button>Click me</button>
</div>

Cuando haces clic en el botón, handleCapture se dispara primero (el evento va hacia abajo), luego se dispara handleBubble (el evento va hacia arriba).

Los manejadores de captura son útiles para interceptar eventos antes de que los hijos los manejen; por ejemplo, implementar atajos de teclado que deberían funcionar independientemente del foco, o crear superposiciones modales que bloqueen la interacción con el contenido de fondo.

Controlar el Comportamiento Predeterminado

Muchos eventos tienen comportamientos predeterminados del navegador: los enlaces navegan, los formularios se envían y recargan la página, el clic derecho muestra un menú contextual. Llama a event.preventDefault() para detener estos comportamientos predeterminados:

<script>
	async function handleSubmit(event) {
		event.preventDefault() // Stop page reload

		const formData = new FormData(event.target)
		const response = await fetch('/api/submit', {
			method: 'POST',
			body: formData
		})

		if (response.ok) {
			// Handle success without page navigation
		}
	}
</script>

<form onsubmit={handleSubmit}>
	<input name="email" type="email" required />
	<button type="submit">Subscribe</button>
</form>

Detener la Propagación

Para evitar que un evento burbujee hacia los manejadores de los elementos padre, usa stopPropagation():

<script>
	function handleButtonClick(event) {
		event.stopPropagation()
		console.log('Button clicked - container handler will NOT fire')
	}

	function handleContainerClick() {
		console.log('Container clicked')
	}
</script>

<div onclick={handleContainerClick}>
	<p>Click here triggers container handler</p>
	<button onclick={handleButtonClick}>Click here only triggers button handler</button>
</div>

Usa stopImmediatePropagation() para también evitar que otros manejadores en el mismo elemento se disparen.

Ten cuidado con stopPropagation(): puede romper funcionalidades que dependen de que los eventos burbujeen, como los patrones de "clic fuera para cerrar" o el análisis que escucha a nivel del documento.

Crear Envoltorios de Modificadores Reutilizables

Si con frecuencia necesitas prevenir el comportamiento predeterminado o detener la propagación, crea funciones auxiliares:

<script>
	function preventDefault(handler) {
		return (event) => {
			event.preventDefault()
			handler(event)
		}
	}

	function stopPropagation(handler) {
		return (event) => {
			event.stopPropagation()
			handler(event)
		}
	}

	// Compose multiple modifiers
	function withModifiers(...modifiers) {
		return (handler) => {
			return (event) => {
				for (const modifier of modifiers) {
					modifier(event)
				}
				handler(event)
			}
		}
	}

	function actualSubmitLogic(event) {
		// Just the business logic, no event mechanics
		const data = new FormData(event.target)
		submitToServer(data)
	}
</script>

<form onsubmit={preventDefault(actualSubmitLogic)}>
	<!-- ... -->
</form>

Esto separa la mecánica de los eventos de la lógica de negocio, haciendo que ambas sean más reutilizables y comprobables.

Eventos de Componentes con Callbacks

Cuando los componentes hijos necesitan notificar a los padres sobre eventos, Svelte 5 usa props de callback: funciones que se pasan del padre al hijo y que el hijo llama cuando algo sucede.

Patrón Básico de Callback

<!-- ColorPicker.svelte -->
<script>
	let { value = '#000000', onChange } = $props()
</script>

<input type="color" {value} oninput={(e) => onChange?.(e.target.value)} />

<!-- App.svelte -->
<script>
	import ColorPicker from './ColorPicker.svelte'

	let selectedColor = $state('#3498db')
</script>

<ColorPicker value={selectedColor} onChange={(color) => (selectedColor = color)} />

<p style="color: {selectedColor}">Selected: {selectedColor}</p>

La sintaxis ?.() (encadenamiento opcional) llama al callback de forma segura solo si fue proporcionado. Esto hace que los callbacks sean opcionales por defecto: los componentes funcionan incluso si los padres no necesitan escuchar.

Convenciones de Nomenclatura

Las props de callback convencionalmente comienzan con on: onClick, onChange, onSubmit, onSelect, onDelete. Esto refleja la nomenclatura de eventos del DOM y señala "este es un gancho de notificación, no datos."

Para componentes complejos, sé más específico: onItemSelect, onFilterChange, onRowDelete. La consistencia dentro de tu base de código importa más que seguir cualquier convención en particular.

Pasar Datos Complejos a Través de Callbacks

Los callbacks pueden llevar cualquier dato que el padre necesite para manejar el evento:

<!-- DataTable.svelte -->
<script>
	let { rows, onRowClick, onRowDelete, onSort } = $props()
</script>

<table>
	<thead>
		<tr>
			<th onclick={() => onSort?.('name', 'asc')}>Name</th>
			<th onclick={() => onSort?.('date', 'desc')}>Date</th>
			<th>Actions</th>
		</tr>
	</thead>
	<tbody>
		{#each rows as row}
			<tr onclick={() => onRowClick?.(row)}>
				<td>{row.name}</td>
				<td>{row.date}</td>
				<td>
					<button
						onclick={(e) => {
							e.stopPropagation() // Don't trigger row click
							onRowDelete?.(row.id)
						}}
					>
						Delete
					</button>
				</td>
			</tr>
		{/each}
	</tbody>
</table>

El padre recibe exactamente la información necesaria para manejar cada interacción:

<script>
	import DataTable from './DataTable.svelte'

	let data = $state([
		/* ... */
	])

	function handleRowClick(row) {
		selectedRow = row
		showDetails = true
	}

	function handleDelete(id) {
		data = data.filter((row) => row.id !== id)
	}

	function handleSort(column, direction) {
		data = [...data].sort((a, b) => {
			const cmp = a[column] > b[column] ? 1 : -1
			return direction === 'asc' ? cmp : -cmp
		})
	}
</script>

<DataTable rows={data} onRowClick={handleRowClick} onRowDelete={handleDelete} onSort={handleSort} />

Callbacks Requeridos vs Opcionales

Haz que los callbacks sean requeridos cuando el padre DEBE manejar el resultado. Usa TypeScript para forzarlo:

<script lang="ts">
	interface Props {
		onConfirm: (result: boolean) => void // Required
		onCancel?: () => void // Optional
	}

	let { onConfirm, onCancel }: Props = $props()
</script>

<div class="dialog">
	<button onclick={() => onConfirm(true)}>Yes</button>
	<button onclick={() => onConfirm(false)}>No</button>
	<button onclick={() => onCancel?.()}>Cancel</button>
</div>

Patrones de Reenvío de Eventos

Al construir componentes contenedores, frecuentemente necesitas pasar eventos desde elementos internos a los consumidores.

Patrón 1: Props de Manejadores Explícitos

Acepta manejadores específicos y adjúntalos a los elementos internos:

<!-- Button.svelte -->
<script>
	let { children, onclick, ondblclick, disabled = false, variant = 'primary' } = $props()
</script>

<button class="btn btn-{variant}" {disabled} {onclick} {ondblclick}>
	{@render children?.()}
</button>

Esto funciona, pero requiere listar explícitamente cada evento que deseas reenviar.

Patrón 2: Rest Props para Reenvío Completo

Recopila props adicionales con la sintaxis rest y espárcelas en el elemento:

<!-- Button.svelte -->
<script>
	let { children, variant = 'primary', ...rest } = $props()
</script>

<button class="btn btn-{variant}" {...rest}>
	{@render children?.()}
</button>

Ahora los consumidores pueden pasar CUALQUIER atributo o manejador de eventos, y llega al botón interno:

<Button
	onclick={handleClick}
	onmouseenter={handleHover}
	disabled={isLoading}
	aria-label="Submit form"
>
	Submit
</Button>

Patrón 3: Interceptar y Luego Reenviar

A veces tu componente necesita hacer algo con un evento Y permitir que el consumidor lo maneje:

<!-- Button.svelte -->
<script>
	let { children, onclick, variant = 'primary', ...rest } = $props()

	function handleClick(event) {
		// Component's internal logic
		trackAnalytics('button_click', { variant })

		// Add visual feedback
		event.target.classList.add('clicked')
		setTimeout(() => event.target.classList.remove('clicked'), 200)

		// Forward to consumer's handler
		onclick?.(event)
	}
</script>

<button class="btn btn-{variant}" {...rest} onclick={handleClick}>
	{@render children?.()}
</button>

Observa el orden: {...rest} va antes de onclick={handleClick}. Esta es una buena práctica para garantizar que tu manejador explícito tenga precedencia sobre cualquier prop esparcida. Aunque desestructuramos onclick (eliminándolo de rest), este patrón te protege si luego cambias la definición de las props. Dentro de tu manejador, llamas al prop onclick original después de que tu lógica se ejecuta.

Este patrón es poderoso para agregar analíticas, animaciones, validación o registro a las interacciones sin que los consumidores necesiten implementarlo por sí mismos.

Eventos de Teclado y Atajos

El manejo del teclado es esencial para aplicaciones accesibles y amigables para usuarios avanzados.

La Propiedad `key`

El manejo moderno del teclado usa la propiedad key, que te proporciona el valor de la tecla como una cadena de texto:

<script>
	function handleKeyDown(event) {
		switch (event.key) {
			case 'Enter':
				submit()
				break
			case 'Escape':
				cancel()
				break
			case 'ArrowDown':
				event.preventDefault() // Prevent scroll
				selectNext()
				break
			case 'ArrowUp':
				event.preventDefault()
				selectPrevious()
				break
		}
	}
</script>

<div tabindex="0" onkeydown={handleKeyDown}>
	<!-- Interactive content -->
</div>

Valores de tecla comunes: Enter, Escape, Tab, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, (espacio), y letras/números como su carácter correspondiente.

Atajos de Teclado con Modificadores

Verifica las propiedades de teclas modificadoras para los atajos de teclado:

<script>
	function handleGlobalKeyDown(event) {
		const isMac = navigator.platform.includes('Mac')
		const modifier = isMac ? event.metaKey : event.ctrlKey

		if (modifier && event.key === 's') {
			event.preventDefault()
			saveDocument()
		}

		if (modifier && event.key === 'k') {
			event.preventDefault()
			openCommandPalette()
		}

		if (modifier && event.shiftKey && event.key === 'z') {
			event.preventDefault()
			redo()
		}

		if (modifier && !event.shiftKey && event.key === 'z') {
			event.preventDefault()
			undo()
		}
	}
</script>

<svelte:window onkeydown={handleGlobalKeyDown} />

Usar <svelte:window> adjunta el manejador al objeto window, capturando eventos de teclado sin importar qué elemento tenga el foco. Esto es ideal para atajos de alcance global en la aplicación.

Hacer que los Elementos Personalizados sean Accesibles por Teclado

Los elementos interactivos personalizados deben soportar interacción por teclado para ser accesibles:

<script>
	let { onActivate, label } = $props()

	function handleKeyDown(event) {
		if (event.key === 'Enter' || event.key === ' ') {
			event.preventDefault() // Prevent space from scrolling
			onActivate?.()
		}
	}
</script>

<div role="button" tabindex="0" onclick={onActivate} onkeydown={handleKeyDown} aria-label={label}>
	{@render children?.()}
</div>

Requisitos clave de accesibilidad:

tabindex="0" hace que el elemento sea enfocable mediante Tab
role="button" le indica a los lectores de pantalla que se comporta como un botón
Enter y Space deben activar la acción (coincidiendo con el comportamiento nativo del botón)
Prevenir el comportamiento de desplazamiento predeterminado de Space

Eventos de Toque y Puntero

Las pantallas táctiles requieren un manejo especial. Svelte 5 tiene un comportamiento específico en torno a los eventos táctiles y de rueda que necesitas entender.

Conceptos Básicos de Eventos Táctiles

Los eventos táctiles proporcionan información sobre el contacto de los dedos:

<script>
	let touchStart = $state(null)
	let offset = $state({ x: 0, y: 0 })

	function handleTouchStart(event) {
		const touch = event.touches[0]
		touchStart = { x: touch.clientX, y: touch.clientY }
	}

	function handleTouchMove(event) {
		if (!touchStart) return
		const touch = event.touches[0]
		offset = {
			x: touch.clientX - touchStart.x,
			y: touch.clientY - touchStart.y
		}
	}

	function handleTouchEnd() {
		touchStart = null
	}
</script>

<div
	class="draggable"
	style="transform: translate({offset.x}px, {offset.y}px)"
	ontouchstart={handleTouchStart}
	ontouchmove={handleTouchMove}
	ontouchend={handleTouchEnd}
>
	Drag me
</div>

Eventos Táctiles Pasivos

Esto es algo crítico: en Svelte 5, los eventos táctiles y de rueda son pasivos por defecto. Esto es una optimización de rendimiento—el navegador no espera tu JavaScript antes de desplazarse, haciendo que la interacción táctil se sienta instantánea.

La implicación: event.preventDefault() es ignorado silenciosamente en los manejadores pasivos:

<!-- preventDefault() does NOTHING here - event is passive -->
<div ontouchmove={(e) => {
  e.preventDefault(); // Silently ignored!
  handleDrag(e);
}}>

En la mayoría de los casos esto está bien. Pero si estás construyendo un canvas de dibujo, gestos personalizados, o cualquier cosa en la que necesites prevenir el desplazamiento, necesitas la función on de svelte/events (cubierta en la siguiente sección).

Eventos de Puntero: Manejo Unificado de Entradas

Los eventos de puntero unifican las entradas de ratón, táctil y lápiz óptico. En lugar de escribir manejadores separados para cada tipo de entrada, escribe un solo manejador que funcione para todos:

<script>
	let isDrawing = $state(false)
	let points = $state([])

	function handlePointerDown(event) {
		isDrawing = true
		points = [{ x: event.clientX, y: event.clientY }]

		// Capture ensures we get events even if pointer leaves the element
		event.target.setPointerCapture(event.pointerId)
	}

	function handlePointerMove(event) {
		if (!isDrawing) return
		points = [...points, { x: event.clientX, y: event.clientY }]
	}

	function handlePointerUp() {
		isDrawing = false
	}
</script>

<svg
	onpointerdown={handlePointerDown}
	onpointermove={handlePointerMove}
	onpointerup={handlePointerUp}
>
	{#if points.length > 1}
		<polyline
			points={points.map((p) => `${p.x},${p.y}`).join(' ')}
			fill="none"
			stroke="black"
			stroke-width="2"
		/>
	{/if}
</svg>

setPointerCapture() es particularmente útil—garantiza que tu elemento continúe recibiendo eventos de puntero incluso si el puntero se mueve fuera de los límites del elemento, lo cual es esencial para operaciones de arrastre.

La Función `on` de svelte/events

Cuando necesitas adjuntar escuchadores de eventos de forma programática (en lugar de hacerlo mediante atributos), Svelte proporciona una función on que preserva el orden correcto de los eventos en relación con los manejadores declarativos.

Svelte usa delegación de eventos para el rendimiento—los manejadores declarativos como onclick en realidad son gestionados por un único escuchador en la raíz del documento. Si usas addEventListener directamente, tu manejador podría ejecutarse en un orden diferente al esperado en relación con los manejadores declarativos.

La función on garantiza el orden correcto y retorna una función de limpieza:

<script>
	import { on } from 'svelte/events'

	let element

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

		// Returns cleanup function automatically
		return on(element, 'click', (event) => {
			console.log('Clicked!')
		})
	})
</script>

<button bind:this={element}>Click me</button>

Eventos de Window y Document

<script>
	import { on } from 'svelte/events'

	let scrollY = $state(0)

	$effect(() => {
		return on(window, 'scroll', () => {
			scrollY = window.scrollY
		})
	})
</script>

Manejadores de Touch No Pasivos

La función on acepta las mismas opciones que addEventListener, incluyendo passive. Esto es útil para eventos táctiles donde necesitas llamar a preventDefault():

<script>
	import { on } from 'svelte/events'

	let canvas
	let ctx
	let isDrawing = $state(false)

	$effect(() => {
		if (!canvas) return
		ctx = canvas.getContext('2d')

		const cleanupStart = on(canvas, 'touchstart', handleTouchStart, { passive: false })
		const cleanupMove = on(canvas, 'touchmove', handleTouchMove, { passive: false })
		const cleanupEnd = on(canvas, 'touchend', handleTouchEnd)

		return () => {
			cleanupStart()
			cleanupMove()
			cleanupEnd()
		}
	})

	function handleTouchStart(event) {
		event.preventDefault() // NOW this works!
		isDrawing = true

		const touch = event.touches[0]
		const rect = canvas.getBoundingClientRect()
		ctx.beginPath()
		ctx.moveTo(touch.clientX - rect.left, touch.clientY - rect.top)
	}

	function handleTouchMove(event) {
		if (!isDrawing) return
		event.preventDefault() // Prevents page scrolling while drawing

		const touch = event.touches[0]
		const rect = canvas.getBoundingClientRect()
		ctx.lineTo(touch.clientX - rect.left, touch.clientY - rect.top)
		ctx.stroke()
	}

	function handleTouchEnd() {
		isDrawing = false
	}
</script>

<canvas bind:this={canvas} width="400" height="300"></canvas>

La opción { passive: false } le indica al navegador que espere a tu manejador antes de ejecutar la acción predeterminada, lo que permite que preventDefault() funcione.

Eventos de Window con Opciones

<script>
	import { on } from 'svelte/events'

	let scrollY = $state(0)
	let lastScrollY = 0
	let scrollDirection = $state('none')

	$effect(() => {
		const cleanup = on(
			window,
			'scroll',
			() => {
				scrollY = window.scrollY
				scrollDirection = scrollY > lastScrollY ? 'down' : 'up'
				lastScrollY = scrollY
			},
			{ passive: true }
		) // Passive is good here - we don't need to prevent

		return cleanup
	})
</script>

<header class:hidden={scrollDirection === 'down' && scrollY > 100}>
	<!-- Hide header when scrolling down -->
</header>

Patrones del Mundo Real

Construyamos algunos patrones interactivos comunes que combinan múltiples conceptos de manejo de eventos.

Clic Fuera para Cerrar

Cierra dropdowns, modales o popovers cuando se hace clic fuera de ellos:

<script>
  let { open = $bindable(false) } = $props();
  let containerRef;

  function handleWindowClick(event) {
    if (containerRef && !containerRef.contains(event.target)) {
      open = false;
    }
  }
</script>

{#if open}
  <svelte:window onclick={handleWindowClick} />
{/if}

<div class="dropdown-wrapper">
  <button onclick={() => open = !open}>
    {open ? 'Close' : 'Open'} Menu
  </button>

  {#if open}
    <div bind:this={containerRef} class="dropdown-menu">
      <button onclick={() => console.log('Action 1')}>Action 1</button>
      <button onclick={() => console.log('Action 2')}>Action 2</button>
      <button onclick={() => open = false}>Close</button>
    </div>
  {/if}
</div>

El método contains() verifica si el elemento en el que se hizo clic está dentro de nuestro contenedor. Si no lo está, cerramos el dropdown. El listener de window solo existe cuando el dropdown está abierto, manteniendo todo eficiente.

Input de Búsqueda con Debounce

Espera a que el usuario deje de escribir antes de ejecutar una búsqueda:

<script>
	let { onSearch } = $props()
	let query = $state('')
	let timeoutId

	function handleInput(event) {
		query = event.target.value

		clearTimeout(timeoutId)
		timeoutId = setTimeout(() => {
			if (query.trim()) {
				onSearch?.(query.trim())
			}
		}, 300)
	}
</script>

<input type="search" value={query} oninput={handleInput} placeholder="Search..." />

Cada pulsación de tecla reinicia el temporizador. La búsqueda solo se ejecuta después de 300ms sin escribir, lo que evita llamadas excesivas a la API mientras el usuario aún está ingresando su consulta.

Lista Navegable con Teclado

Una lista que soporta navegación con teclas de flecha, Enter para seleccionar y Home/End:

<script>
	let { items, onSelect } = $props()
	let selectedIndex = $state(0)
	let listRef

	function handleKeyDown(event) {
		switch (event.key) {
			case 'ArrowDown':
				event.preventDefault()
				selectedIndex = Math.min(selectedIndex + 1, items.length - 1)
				scrollIntoView()
				break

			case 'ArrowUp':
				event.preventDefault()
				selectedIndex = Math.max(selectedIndex - 1, 0)
				scrollIntoView()
				break

			case 'Enter':
				event.preventDefault()
				onSelect?.(items[selectedIndex])
				break

			case 'Home':
				event.preventDefault()
				selectedIndex = 0
				scrollIntoView()
				break

			case 'End':
				event.preventDefault()
				selectedIndex = items.length - 1
				scrollIntoView()
				break
		}
	}

	function scrollIntoView() {
		listRef?.children[selectedIndex]?.scrollIntoView({ block: 'nearest' })
	}
</script>

<ul bind:this={listRef} role="listbox" tabindex="0" onkeydown={handleKeyDown}>
	{#each items as item, i}
		<li
			role="option"
			class:selected={i === selectedIndex}
			aria-selected={i === selectedIndex}
			onclick={() => {
				selectedIndex = i
				onSelect?.(item)
			}}
		>
			{item.label}
		</li>
	{/each}
</ul>

<style>
	ul {
		list-style: none;
		padding: 0;
		margin: 0;
		max-height: 200px;
		overflow-y: auto;
		border: 1px solid #ddd;
		border-radius: 4px;
	}

	ul:focus {
		outline: 2px solid #3498db;
		outline-offset: 2px;
	}

	li {
		padding: 8px 12px;
		cursor: pointer;
	}

	li:hover {
		background: #f5f5f5;
	}

	li.selected {
		background: #3498db;
		color: white;
	}
</style>

Esto combina eventos de teclado, atributos ARIA para accesibilidad, interacción con el mouse y gestión del scroll en un componente pulido y accesible.

Los modales deben atrapar el foco en su interior: Tab no debería escapar hacia la página de fondo:

<script>
	let { open = $bindable(false), children } = $props()
	let modalRef
	let previousFocus

	$effect(() => {
		if (open) {
			previousFocus = document.activeElement

			// Focus first focusable element
			setTimeout(() => {
				const focusable = getFocusableElements()
				focusable[0]?.focus()
			}, 0)
		} else if (previousFocus) {
			previousFocus.focus()
		}
	})

	function getFocusableElements() {
		if (!modalRef) return []
		return [
			...modalRef.querySelectorAll(
				'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
			)
		]
	}

	function handleKeyDown(event) {
		if (event.key === 'Escape') {
			open = false
			return
		}

		if (event.key === 'Tab') {
			const focusable = getFocusableElements()
			if (focusable.length === 0) return

			const first = focusable[0]
			const last = focusable[focusable.length - 1]

			if (event.shiftKey && document.activeElement === first) {
				event.preventDefault()
				last.focus()
			} else if (!event.shiftKey && document.activeElement === last) {
				event.preventDefault()
				first.focus()
			}
		}
	}

	function handleBackdropClick(event) {
		if (event.target === event.currentTarget) {
			open = false
		}
	}
</script>

{#if open}
	<div
		class="modal-backdrop"
		onclick={handleBackdropClick}
		onkeydown={handleKeyDown}
		role="dialog"
		aria-modal="true"
	>
		<div bind:this={modalRef} class="modal-content">
			<button class="close-btn" onclick={() => (open = false)}>×</button>
			{@render children?.()}
		</div>
	</div>
{/if}

<style>
	.modal-backdrop {
		position: fixed;
		inset: 0;
		background: rgba(0, 0, 0, 0.5);
		display: flex;
		align-items: center;
		justify-content: center;
	}

	.modal-content {
		background: white;
		padding: 24px;
		border-radius: 8px;
		max-width: 500px;
		width: 90%;
		position: relative;
	}

	.close-btn {
		position: absolute;
		top: 8px;
		right: 8px;
		border: none;
		background: none;
		font-size: 24px;
		cursor: pointer;
	}
</style>

Este modal implementa una gestión adecuada del foco: guarda el foco anterior, mueve el foco al interior del modal, atrapa Tab/Shift+Tab para ciclar entre los elementos del modal, cierra al presionar Escape y restaura el foco al cerrar.

Arrastrar y Soltar con Ordenamiento

Una lista que puede reordenarse arrastrando:

<script>
	let { items = $bindable([]) } = $props()
	let draggedIndex = $state(null)
	let dragOverIndex = $state(null)

	function handleDragStart(event, index) {
		draggedIndex = index
		event.dataTransfer.effectAllowed = 'move'
		// Required for Firefox
		event.dataTransfer.setData('text/plain', index.toString())
	}

	function handleDragOver(event, index) {
		event.preventDefault()
		event.dataTransfer.dropEffect = 'move'
		dragOverIndex = index
	}

	function handleDragLeave() {
		dragOverIndex = null
	}

	function handleDrop(event, dropIndex) {
		event.preventDefault()

		if (draggedIndex === null || draggedIndex === dropIndex) return

		const newItems = [...items]
		const [removed] = newItems.splice(draggedIndex, 1)
		newItems.splice(dropIndex, 0, removed)
		items = newItems

		draggedIndex = null
		dragOverIndex = null
	}

	function handleDragEnd() {
		draggedIndex = null
		dragOverIndex = null
	}
</script>

<ul class="sortable-list">
	{#each items as item, index (item.id)}
		<li
			draggable="true"
			class:dragging={draggedIndex === index}
			class:drag-over={dragOverIndex === index}
			ondragstart={(e) => handleDragStart(e, index)}
			ondragover={(e) => handleDragOver(e, index)}
			ondragleave={handleDragLeave}
			ondrop={(e) => handleDrop(e, index)}
			ondragend={handleDragEnd}
		>
			<span class="drag-handle">⋮⋮</span>
			{item.label}
		</li>
	{/each}
</ul>

<style>
	.sortable-list {
		list-style: none;
		padding: 0;
		margin: 0;
	}

	li {
		display: flex;
		align-items: center;
		gap: 8px;
		padding: 12px;
		background: white;
		border: 1px solid #ddd;
		margin-bottom: -1px;
		cursor: grab;
		transition: background-color 0.2s;
	}

	li:active {
		cursor: grabbing;
	}

	li.dragging {
		opacity: 0.5;
		background: #f0f0f0;
	}

	li.drag-over {
		border-top: 2px solid #3498db;
		margin-top: -1px;
	}

	.drag-handle {
		color: #999;
		user-select: none;
	}
</style>

Esto utiliza la API de Arrastrar y Soltar de HTML5 con retroalimentación visual para el estado de arrastre y la indicación del destino de soltar.

Errores Comunes

Olvidar la Sensibilidad a Mayúsculas y Minúsculas

<!-- WRONG: onClick listens for custom "Click" event, not standard click -->
<button onClick={handleClick}>Click me</button>

<!-- CORRECT: onclick for standard click event -->
<button onclick={handleClick}>Click me</button>

Detener la Propagación Rompe la Delegación

Si agregas listeners de eventos manuales con stopPropagation(), los manejadores delegados de Svelte no se ejecutarán:

// This breaks Svelte's event handling!
element.addEventListener('click', (e) => {
	e.stopPropagation()
	// Svelte's onclick handlers on this or parent elements won't fire
})

Usa la función on de svelte/events si necesitas listeners manuales que se integren correctamente.

Esperar que preventDefault Funcione en Eventos Touch

<!-- preventDefault is IGNORED - touch events are passive by default -->
<div ontouchmove={(e) => {
  e.preventDefault(); // Does nothing!
  handleDrag(e);
}}>

Usa la función on con { passive: false } cuando necesites prevenir los comportamientos predeterminados táctiles.

Orden de Manejadores con Spreads

Cuando se hace spread de props en un elemento, el último atributo tiene precedencia. Si rest contiene un manejador onclick (porque no lo desestructuraste), el orden importa:

<!-- Your handler overrides onclick from rest props -->
<button {...rest} onclick={handleClick}>

<!-- onclick from rest props will override your handler -->
<button onclick={handleClick} {...rest}>

Si quieres interceptar Y reenviar, extrae el manejador primero:

<script>
  let { onclick, ...rest } = $props();

  function handleClick(event) {
    // Your logic first
    doSomething();
    // Then forward
    onclick?.(event);
  }
</script>

<button {...rest} onclick={handleClick}>

Olvidar el Parámetro de Evento en Funciones de Flecha

<!-- WRONG: event is undefined -->
<button onclick={() => handleClick(event)}>

<!-- CORRECT: capture event from arrow function parameter -->
<button onclick={(event) => handleClick(event)}>

<!-- Or just pass the handler directly if you don't need extra data -->
<button onclick={handleClick}>

Conclusión

El manejo de eventos en Svelte 5 es sencillo pero poderoso. Los conceptos clave:

Los atributos de evento (onclick, onkeydown, etc.) hacen que los eventos sean consistentes con otras propiedades de los elementos. Son sensibles a mayúsculas y minúsculas: usa minúsculas para los eventos estándar del DOM.

La delegación de eventos ocurre automáticamente para los eventos comunes, mejorando el rendimiento. Los eventos personalizados necesitan bubbles: true para participar.

Los callbacks de componentes reemplazan el despacho de eventos. Pasa funciones como props y llámalas cuando ocurran cosas. Usa ?.() para callbacks opcionales.

La función on maneja casos especiales: eventos táctiles no pasivos, opciones específicas de addEventListener, y eventos de window/document más allá de lo que <svelte:window> ofrece.

Los patrones del mundo real combinan estos conceptos: clic fuera para cerrar, trampa de foco, navegación con teclado, arrastrar y soltar. Entender la propagación, la captura y el objeto de evento te permite construir interacciones sofisticadas.

Con estas bases, puedes crear aplicaciones que se sientan responsivas y naturales de usar.