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

Los eventos son la manera 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 elementos, lo que los hace consistentes con la forma en que se configuran otras propiedades. Esta guía cubre todo, desde manejadores de clics básicos hasta patrones complejos como el bloqueo de foco y el manejo de gestos.

Atributos de Eventos: Lo Básico

Svelte 5 utiliza 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 flecha en línea funcionan bien y no tienen penalización de rendimiento en Svelte:

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

Funciones Nombradas vs Manejadores en Línea

Usa funciones nombradas cuando tu manejador tiene múltiples pasos, necesita un nombre descriptivo para mayor 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 nombrada sería excesiva:

<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 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 flecha crea un cierre que captura el task.id específico de 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 del Evento 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=central, 2=derecho), y los 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 está presionada de forma continua).

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 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 activará 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 utiliza 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 correspondientes.

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

Sin embargo, esto tiene implicaciones que deberías entender:

Los eventos personalizados deben burbujear. Si despachas 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 en 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 handleBubble se dispara (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 deben 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 integrados 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 prevenir que otros manejadores en el mismo elemento se disparen.

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

Crear Envoltorios de Modificadores Reutilizables

Si frecuentemente 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 testeables.

Eventos de Componentes con Callbacks

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

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 aunque los padres no necesiten escuchar.

Convenciones de Nomenclatura

Los props de callback convencionalmente comienzan con on: onClick, onChange, onSubmit, onSelect, onDelete. Esto refleja la nomenclatura de eventos del DOM y señala "esto es un hook 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 Enriquecidos 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 aplicar esto:

<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 envolventes, frecuentemente necesitas pasar eventos de elementos internos a los consumidores.

Patrón 1: Props de Manejadores Explícitos

Acepta manejadores específicos y adjúntalos a 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 distribúyelas 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 llegará 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 dejar 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>

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

Este patrón es poderoso para agregar analíticas, animaciones, validación o registro a las interacciones sin que los consumidores necesiten implementarlo ellos 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 de 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 teclas comunes: Enter, Escape, Tab, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, (espacio), y letras/números como su carácter.

Atajos de Teclado con Modificadores

Verifica las propiedades de las 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 independientemente de qué elemento tenga el foco. Esto es ideal para atajos a nivel de aplicación.

Hacer que los Elementos Personalizados sean Accesibles por Teclado

Los elementos interactivos personalizados deben soportar la 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 este elemento 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 predeterminado de desplazamiento de Space

Eventos Táctiles y de 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 proveen 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

Aquí hay 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 a tu JavaScript antes de desplazarse, haciendo que la interacción táctil se sienta instantánea.

La implicación: event.preventDefault() se ignora silenciosamente en los manejadores pasivos:

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

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

Eventos de Puntero: Manejo Unificado de Entrada

Los eventos de puntero unifican la entrada de ratón, táctil y lápiz óptico. En lugar de escribir manejadores separados para cada tipo de entrada, escribe un único 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 arrastrar.

La Función `on` de svelte/events

Cuando necesitas adjuntar escuchadores de eventos de manera programática (en lugar de a través de atributos), Svelte provee una función on que preserva el orden correcto de eventos en relación a los manejadores declarativos.

Svelte usa delegación de eventos por rendimiento—los manejadores declarativos como onclick son en realidad manejados 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 a los manejadores declarativos.

La función on asegura 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 cuando 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 tu manejador antes de tomar 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 al hacer 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 las cosas eficientes.

Input de Búsqueda con Debounce

Espera a que el usuario deje de escribir antes de disparar 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—evitando 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 detrás:

<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, se cierra con Escape y restaura el foco al cerrarse.

Arrastrar y Soltar Ordenable

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 Drag and Drop de HTML5 con retroalimentación visual para el estado de arrastre e indicación del objetivo 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 Interrumpe 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 Táctiles

<!-- 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 de los eventos táctiles.

Orden de Manejadores con Spreads

Al aplicar spread de props a un elemento, el último atributo tiene prioridad. 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 primero el manejador:

<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 DOM estándar.

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, llámalas cuando ocurran cosas. Usa ?.() para callbacks opcionales.

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

Los patrones del mundo real combinan estos conceptos: clic fuera para cerrar, trampa de foco, navegación con teclado, arrastrar y soltar. Comprender 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.