O Guia Completo de Manipulação de Eventos no Svelte

Eventos são a forma como sua aplicação responde à interação do usuário — cliques, teclas pressionadas, toques, envios de formulário. O Svelte 5 lida com eventos por meio de atributos de elemento, tornando-os consistentes com a forma como você define outras propriedades. Este guia cobre tudo, desde manipuladores de clique básicos até padrões complexos como armadilha de foco e manipulação de gestos.

Atributos de Eventos: O Básico

O Svelte 5 usa atributos de eventos HTML padrão: onclick, onkeydown, onsubmit, onmousemove. Quando você atribui uma função a eles, essa função é chamada sempre que o evento ocorre naquele elemento.

<script>
	let count = $state(0)

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

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

Para operações simples, funções de seta inline funcionam bem e não têm penalidade de desempenho no Svelte:

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

Funções Nomeadas vs Manipuladores Inline

Use funções nomeadas quando seu manipulador tiver múltiplas etapas, precisar de um nome descritivo para legibilidade ou for 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>

Use manipuladores inline para ações simples e de propósito único onde uma função nomeada seria excessiva:

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

Trabalhando com o Objeto de Evento

Quando um evento é disparado, o navegador cria um objeto de evento contendo informações sobre o que aconteceu. O Svelte passa esse objeto para sua função manipuladora automaticamente.

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

Passando Dados Personalizados para Manipuladores

Muitas vezes você precisa passar dados adicionais para seu manipulador — como qual item de uma lista foi clicado. Envolva seu manipulador em uma função de seta para capturar esses dados:

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

A função de seta cria um closure que captura o task.id específico de cada item da lista. Ao ser clicado, ela chama deleteTask com esse ID.

Se você precisar tanto do objeto de evento QUANTO de dados 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>

Propriedades de Evento Chave por Tipo

Eventos de mouse incluem clientX/clientY (coordenadas da viewport), pageX/pageY (coordenadas do documento), button (qual botão: 0=esquerdo, 1=meio, 2=direito) e estados das teclas modificadoras (shiftKey, ctrlKey, altKey, metaKey).

Eventos de teclado incluem key (o valor da tecla como "Enter", "a", "ArrowDown"), code (tecla física como "KeyA" independente do layout) e repeat (verdadeiro se a tecla estiver pressionada).

Eventos de formulário fornecem event.target como o elemento do formulário, que você pode passar para FormData ou acessar campos individuais via event.target.elements.

Propagação de Eventos e Delegação

Quando você clica em um botão dentro de uma div, ambos os elementos podem potencialmente tratar esse clique. O navegador envia eventos por três fases:

Fase de captura: O evento desce do window até o alvo
Fase de alvo: O evento chega ao elemento que foi efetivamente clicado
Fase de borbulhamento: O evento sobe de volta do alvo até o window

Por padrão, os manipuladores disparam durante a fase de borbulhamento. Isso significa que um clique em um elemento aninhado vai borbulhar para cima e acionar manipuladores nos elementos pai também.

Target vs CurrentTarget

Essa distinção importa quando você anexa um manipulador a um contêiner, mas os usuários clicam em filhos dentro dele:

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

Clique no parágrafo: target é P, currentTarget é DIV. Clique no botão: target é BUTTON, currentTarget é DIV.

Delegação de Eventos no Svelte

O Svelte usa delegação de eventos para eventos comuns como click, input, keydown e muitos outros. Em vez de anexar um listener a cada elemento, o Svelte anexa um único listener na raiz do documento e roteia os eventos para os manipuladores apropriados.

Isso acontece automaticamente e de forma transparente — você escreve os manipuladores normalmente e o Svelte otimiza nos bastidores. Os benefícios são significativos: menor uso de memória, melhor desempenho com conteúdo dinâmico e nenhuma limpeza manual necessária.

No entanto, há implicações que você deve entender:

Eventos personalizados devem borbulhar. Se você despachar eventos personalizados manualmente, inclua bubbles: true ou a delegação do Svelte não os 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 }))

Parar a propagação pode quebrar coisas. Se você adicionar um addEventListener manual e chamar stopPropagation(), o evento não chegará ao listener raiz do Svelte. Use a função on de svelte/events se precisar de listeners manuais que se integrem à delegação do Svelte.

Manipuladores da Fase de Captura

Para tratar eventos durante a fase de captura (antes de chegarem ao alvo), adicione capture ao nome do 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>

Quando você clica no botão, handleCapture dispara primeiro (evento descendo) e depois handleBubble dispara (evento subindo).

Manipuladores de captura são úteis para interceptar eventos antes que os filhos os tratem — por exemplo, implementar atalhos de teclado que devem funcionar independentemente do foco, ou criar sobreposições modais que bloqueiam a interação com o conteúdo de fundo.

Controlando o Comportamento Padrão

Muitos eventos têm comportamentos nativos do navegador: links navegam, formulários são enviados e recarregam a página, clique com o botão direito exibe um menu de contexto. Chame event.preventDefault() para interromper esses padrões:

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

Parando a Propagação

Para evitar que um evento borbulhe para os manipuladores dos elementos pai, use 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>

Use stopImmediatePropagation() para também impedir que outros manipuladores no mesmo elemento sejam acionados.

Seja cauteloso com stopPropagation() — ele pode quebrar recursos que dependem do borbulhamento de eventos, como padrões de "clicar fora para fechar" ou análises que escutam no nível do documento.

Criando Wrappers de Modificadores Reutilizáveis

Se você frequentemente precisa prevenir o comportamento padrão ou parar a propagação, crie funções 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>

Isso separa a mecânica de eventos da lógica de negócio, tornando ambos mais reutilizáveis e testáveis.

Eventos de Componente com Callbacks

Quando componentes filhos precisam notificar os pais sobre eventos, o Svelte 5 usa props de callback — funções passadas do pai para o filho que o filho chama quando algo acontece.

Padrão 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>

A sintaxe ?.() (encadeamento opcional) chama o callback com segurança apenas se ele foi fornecido. Isso torna os callbacks opcionais por padrão — os componentes funcionam mesmo que os pais não precisem escutar.

Convenções de Nomenclatura

Props de callback convencionalmente começam com on: onClick, onChange, onSubmit, onSelect, onDelete. Isso espelha a nomenclatura de eventos do DOM e sinaliza "isto é um gancho de notificação, não um dado."

Para componentes complexos, seja mais específico: onItemSelect, onFilterChange, onRowDelete. A consistência dentro da sua base de código importa mais do que seguir qualquer convenção específica.

Passando Dados Ricos Através de Callbacks

Callbacks podem carregar quaisquer dados que o pai precise para tratar o 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>

O pai recebe exatamente as informações necessárias para tratar cada interação:

<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 Obrigatórios vs Opcionais

Torne os callbacks obrigatórios quando o pai DEVE tratar o resultado. Use TypeScript para impor isso:

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

Padrões de Encaminhamento de Eventos

Ao construir componentes wrapper, você frequentemente precisa passar eventos de elementos internos para os consumidores.

Padrão 1: Props de Handler Explícitas

Aceite handlers específicos e os anexe 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>

Isso funciona, mas requer listar explicitamente cada evento que você deseja encaminhar.

Padrão 2: Rest Props para Encaminhamento Completo

Colete props extras com a sintaxe rest e espalhe-as no elemento:

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

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

Agora os consumidores podem passar QUALQUER atributo ou handler de evento, e ele chegará ao botão interno:

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

Padrão 3: Interceptar e Encaminhar

Às vezes seu componente precisa fazer algo com um evento E deixar o consumidor tratá-lo:

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

Note a ordem: {...rest} vem antes de onclick={handleClick}. Essa é uma boa prática para garantir que seu handler explícito tenha precedência sobre quaisquer props espalhadas. Embora tenhamos desestruturado onclick (removendo-o de rest), esse padrão protege você se você posteriormente alterar a definição das props. Dentro do seu handler, você chama a prop onclick original após sua lógica ser executada.

Esse padrão é poderoso para adicionar analytics, animações, validação ou logging às interações sem que os consumidores precisem implementá-los por conta própria.

Eventos de Teclado e Atalhos

O tratamento de teclado é essencial para aplicações acessíveis e amigáveis a usuários avançados.

A Propriedade `key`

O tratamento moderno de teclado usa a propriedade key, que fornece o valor da tecla como uma string:

<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 comuns: Enter, Escape, Tab, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, (espaço) e letras/números como seus caracteres.

Atalhos de Teclado com Modificadores

Verifique as propriedades de teclas modificadoras para atalhos 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> anexa o handler ao objeto window, capturando eventos de teclado independentemente de qual elemento está em foco. Isso é ideal para atalhos em nível de aplicação.

Tornando Elementos Personalizados Acessíveis pelo Teclado

Elementos interativos personalizados devem suportar interação por teclado para acessibilidade:

<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 essenciais de acessibilidade:

tabindex="0" torna o elemento focalizável via Tab
role="button" informa aos leitores de tela que ele se comporta como um botão
Enter e Space devem acionar a ativação (correspondendo ao comportamento nativo do botão)
Prevenir o comportamento padrão de rolagem do Space

Eventos de Toque e Ponteiro

Telas sensíveis ao toque requerem tratamento especial. O Svelte 5 possui um comportamento específico em relação a eventos de toque e de roda do mouse que você precisa entender.

Fundamentos dos Eventos de Toque

Os eventos de toque fornecem informações sobre o contato dos 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 de Toque Passivos

Aqui está algo crítico: no Svelte 5, eventos de toque e de roda do mouse são passivos por padrão. Isso é uma otimização de desempenho — o navegador não aguarda seu JavaScript antes de rolar, fazendo com que a interação por toque pareça instantânea.

A implicação: event.preventDefault() é silenciosamente ignorado em handlers passivos:

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

Na maioria dos casos isso é aceitável. Mas se você estiver construindo um canvas de desenho, gestos personalizados ou qualquer coisa onde precise impedir a rolagem, você precisa da função on de svelte/events (abordada na próxima seção).

Eventos de Ponteiro: Tratamento Unificado de Entrada

Os eventos de ponteiro unificam entrada de mouse, toque e caneta. Em vez de escrever handlers separados para cada tipo de entrada, escreva um único handler 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() é particularmente útil — garante que seu elemento continue recebendo eventos de ponteiro mesmo que o ponteiro se mova para fora dos limites do elemento, o que é essencial para operações de arrastar.

A Função `on` de svelte/events

Quando você precisa anexar listeners de evento programaticamente (em vez de por meio de atributos), o Svelte fornece uma função on que preserva a ordem correta dos eventos em relação aos handlers declarativos.

O Svelte usa delegação de eventos para desempenho — handlers declarativos como onclick são na verdade tratados por um único listener na raiz do documento. Se você usar addEventListener diretamente, seu handler pode disparar em uma ordem diferente da esperada em relação aos handlers declarativos.

A função on garante a ordenação correta e retorna uma função de limpeza:

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

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

	let scrollY = $state(0)

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

Handlers de Toque Não-Passivos

A função on aceita as mesmas opções que addEventListener, incluindo passive. Isso é útil para eventos de toque onde você precisa chamar 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>

A opção { passive: false } instrui o navegador a aguardar seu handler antes de executar a ação padrão, permitindo que preventDefault() funcione.

Eventos de Window com Opções

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

Padrões do Mundo Real

Vamos construir alguns padrões interativos comuns que combinam múltiplos conceitos de tratamento de eventos.

Clicar Fora para Fechar

Feche dropdowns, modais ou popovers ao clicar fora:

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

O método contains() verifica se o elemento clicado está dentro do nosso contêiner. Se não estiver, fechamos o dropdown. O listener do window só existe quando o dropdown está aberto, mantendo as coisas eficientes.

Input de Busca com Debounce

Aguarde o usuário parar de digitar antes de disparar uma busca:

<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 pressionamento de tecla reinicia o timer. A busca só é disparada após 300ms sem digitação — evitando chamadas excessivas à API enquanto o usuário ainda está inserindo sua consulta.

Lista com Navegação por Teclado

Uma lista que suporta navegação pelas teclas de seta, Enter para selecionar e 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>

Isso combina eventos de teclado, atributos ARIA para acessibilidade, interação com mouse e gerenciamento de scroll em um componente polido e acessível.

Modais devem prender o foco dentro deles — o Tab não deve escapar para a página por trá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 o gerenciamento adequado de foco: salvando o foco anterior, movendo o foco para dentro do modal, prendendo Tab/Shift+Tab para ciclar pelos elementos do modal, fechando no Escape e restaurando o foco ao fechar.

Arrastar e Soltar para Ordenação

Uma lista que pode ser reordenada arrastando:

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

Isso utiliza a API de Arrastar e Soltar do HTML5 com feedback visual para o estado de arrasto e indicação do alvo de soltura.

Armadilhas Comuns

Esquecer a Sensibilidade a Maiúsculas e 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>

Interromper a Propagação Quebrando a Delegação

Se você adicionar listeners de eventos manuais com stopPropagation(), os handlers delegados do Svelte não serão disparados:

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

Use a função on de svelte/events se precisar de listeners manuais que se integrem corretamente.

Esperar preventDefault em Eventos de Toque

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

Use a função on com { passive: false } quando precisar impedir os padrões de toque.

Ordem dos Handlers com Spreads

Ao aplicar spread de props em um elemento, o último atributo vence. Se rest contiver um handler onclick (porque você não o desestruturou), a ordem importa:

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

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

Se você quiser interceptar E encaminhar, extraia o handler primeiro:

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

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

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

Esquecer o Parâmetro de Evento em Arrow Functions

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

Conclusão

O tratamento de eventos no Svelte 5 é simples, porém poderoso. Os conceitos-chave:

Atributos de evento (onclick, onkeydown, etc.) tornam os eventos consistentes com outras propriedades de elemento. São sensíveis a maiúsculas e minúsculas — use minúsculas para eventos DOM padrão.

A delegação de eventos acontece automaticamente para eventos comuns, melhorando o desempenho. Eventos customizados precisam de bubbles: true para participar.

Callbacks de componente substituem o despacho de eventos. Passe funções como props, chame-as quando algo acontecer. Use ?.() para callbacks opcionais.

A função on lida com casos especiais: eventos de toque não-passivos, opções específicas de addEventListener e eventos de window/document além do que <svelte:window> oferece.

Padrões do mundo real combinam esses conceitos: clicar fora para fechar, armadilha de foco, navegação por teclado, arrastar e soltar. Entender propagação, captura e o objeto de evento permite construir interações sofisticadas.

Com essas bases, você pode criar aplicações que parecem responsivas e naturais de usar.