Fluxo de Dados Bidirecional Simplificado

Na maioria dos frameworks, os dados fluem em uma direção: do estado do componente para o DOM. Quando um usuário digita em um campo de entrada, você precisa escutar eventos manualmente e atualizar o estado. Esse padrão — embora explícito — gera código repetitivo que obscurece a intenção e torna interações simples trabalhosas.

Considere este cenário comum: você tem uma entrada de busca e quer filtrar uma lista enquanto o usuário digita. Sem vinculação, você precisa de manipuladores de eventos, atualizações de estado e coordenação cuidadosa:

<script>
	let searchTerm = $state('')

	function handleInput(event) {
		searchTerm = event.target.value
	}
</script>

<input value={searchTerm} oninput={handleInput} />

A diretiva bind: do Svelte elimina esse atrito ao estabelecer uma vinculação de dados bidirecional: quando o estado muda, a UI atualiza automaticamente, e quando o usuário interage com elementos vinculados, o estado atualiza automaticamente. Essa sincronização bidirecional transforma padrões comuns, como o tratamento de formulários, de uma coreografia de múltiplas etapas em simplicidade declarativa:

<script>
	let searchTerm = $state('')
</script>

<input bind:value={searchTerm} />

Uma linha. Sem manipuladores de eventos. Sem cerimônias. O estado e a entrada permanecem perfeitamente sincronizados.

Por que isso importa: A vinculação bidirecional não é sobre escrever menos código — é sobre expressar a intenção com clareza. Quando você escreve bind:value={searchTerm}, você está declarando um relacionamento: "esta entrada e esta variável são duas visões dos mesmos dados." O Svelte cuida de toda a mecânica de sincronização por você.

Este tutorial explora a diretiva bind: de forma abrangente: desde vinculações básicas de entrada até vinculações avançadas de props de componentes, de propriedades somente leitura de mídia a medições de dimensões, de comportamentos de reset de formulários a otimização de desempenho. Você entenderá não apenas a sintaxe, mas o modelo mental que torna as vinculações poderosas e os padrões que as mantêm gerenciáveis.

Entendendo o Fluxo de Dados

O Padrão Padrão de Fluxo Unidirecional

Por padrão, os dados no Svelte (e na maioria dos frameworks reativos) fluem para baixo:

<script>
	let name = $state('Alice')
</script>

<p>Hello, {name}!</p>

Quando name muda, o parágrafo atualiza. Simples, previsível e unidirecional. Isso funciona perfeitamente para exibição, mas e quanto à entrada do usuário?

Sem vinculação, capturar a entrada do usuário requer tratamento explícito de eventos:

<script>
	let name = $state('Alice')

	function handleInput(event) {
		name = event.target.value
	}
</script>

<input value={name} oninput={handleInput} /><p>Hello, {name}!</p>

Você está fechando o loop manualmente: estado → DOM (via value) e DOM → estado (via oninput). Esse padrão é verboso, mas transparente — você pode ver exatamente o que está acontecendo.

O Atalho da Vinculação Bidirecional

A diretiva bind: automatiza esse loop:

<script>
	let name = $state('Alice')
</script>

<input bind:value={name} /><p>Hello, {name}!</p>

Por baixo dos panos, o Svelte cria o ouvinte de evento para você. Quando a entrada dispara um evento input, o Svelte atualiza name. Quando seu código atualiza name, o Svelte atualiza a propriedade value da entrada. Os dois ficam sincronizados automaticamente.

Modelo mental: Pense no bind: como a criação de uma "conexão ao vivo" entre uma variável e uma propriedade do DOM. Qualquer mudança em qualquer uma das extremidades se propaga para a outra instantaneamente.

Quando Usar Cada Abordagem

Use bind: quando:

O relacionamento é direto: "esta entrada controla esta variável"
Você não precisa transformar, validar ou interceptar o valor durante as atualizações
Você está construindo formulários, painéis de configurações ou controles interativos

Use manipuladores de eventos explícitos quando:

Você precisa transformar a entrada (ex.: remover espaços, converter para minúsculas, sanitizar)
Você precisa validar antes de aceitar as mudanças
Você precisa acionar efeitos colaterais (chamadas de API, analytics)
A lógica é complexa o suficiente para que a explicitude auxilie na compreensão

Ambas as abordagens são válidas. Use bind: para simplicidade, manipuladores de eventos para controle.

Vinculações Básicas de Entrada

Entradas de Texto: `bind:value`

A vinculação mais comum sincroniza o valor de um elemento <input> com uma variável:

<script>
	let username = $state('')
	let email = $state('')
	let bio = $state('')
</script>

<form>
	<label>
		Username:
		<input type="text" bind:value={username} />
	</label>

	<label>
		Email:
		<input type="email" bind:value={email} />
	</label>

	<label>
		Bio:
		<textarea bind:value={bio}></textarea>
	</label>
</form>

<div class="preview">
	<p><strong>Username:</strong> {username || '(empty)'}</p>
	<p><strong>Email:</strong> {email || '(empty)'}</p>
	<p><strong>Bio:</strong> {bio || '(empty)'}</p>
</div>

Como funciona: O Svelte escuta o evento input no elemento. Toda vez que o usuário digita, o evento dispara e o Svelte lê event.target.value e atribui à sua variável. Se você alterar a variável programaticamente (ex.: username = 'Bob'), o Svelte atualiza a propriedade value da entrada e o DOM reflete a mudança.

Sintaxe abreviada: Quando o nome da variável coincide com o nome da propriedade, você pode omitir o valor:

<input bind:value />
<!-- Same as: -->
<input bind:value />

Isso só funciona quando a variável se chama literalmente value. É uma pequena conveniência para casos comuns.

Entradas Numéricas: Coerção de Tipo Automática

Para <input type="number"> e <input type="range">, o Svelte converte automaticamente o valor string em número:

<script>
	let quantity = $state(1)
	let price = $state(9.99)
	let discount = $state(0)

	let total = $derived((quantity * price * (1 - discount / 100)).toFixed(2))
</script>

<div class="calculator">
	<label>
		Quantity:
		<input type="number" bind:value={quantity} min="1" />
	</label>

	<label>
		Price per item: $
		<input type="number" bind:value={price} min="0" step="0.01" />
	</label>

	<label>
		Discount: {discount}%
		<input type="range" bind:value={discount} min="0" max="50" />
	</label>

	<p class="total">Total: ${total}</p>
</div>

Por que a coerção automática importa: Em HTML, todos os valores de formulário são strings. Sem coerção, você precisaria chamar parseFloat() ou parseInt() manualmente em cada valor. O Svelte cuida disso para você, então quantity e price são números reais, não strings.

Caso extremo — entradas vazias ou inválidas: Se uma entrada numérica estiver vazia ou contiver caracteres inválidos, o valor vinculado se torna undefined (não NaN ou "" como em alguns frameworks). Planeje para isso:

<script>
	let age = $state(undefined)

	let isValid = $derived(age !== undefined && age > 0 && age < 150)
</script>

<input type="number" bind:value={age} placeholder="Your age" />

{#if age === undefined}
	<p class="hint">Please enter your age</p>
{:else if !isValid}
	<p class="error">Please enter a valid age (1-150)</p>
{:else}
	<p class="success">Age: {age}</p>
{/if}

Por que undefined e não NaN? O Svelte trata entradas numéricas vazias/inválidas como "nenhum valor fornecido" em vez de "erro de análise numérica." Isso facilita distinguir entre "o usuário ainda não digitou nada" e "o usuário digitou algo, e é zero."

Valores Padrão e Reset de Formulário

Desde o Svelte 5.6, as entradas podem ter um atributo defaultValue. Quando a entrada faz parte de um formulário e o formulário é resetado, a entrada reverte para esse valor padrão em vez de ficar vazia:

<script>
	let name = $state('') // Starts empty
	let email = $state('user@example.com') // Starts with value
</script>

<form>
	<label>
		Name:
		<input bind:value={name} defaultValue="Guest" />
	</label>

	<label>
		Email:
		<input bind:value={email} defaultValue="user@example.com" />
	</label>

	<button type="reset">Reset Form</button>
</form>

<p>Name: {name || '(empty)'}</p>
<p>Email: {email}</p>

Como funciona: Quando você clica em "Reset", o mecanismo nativo de reset do formulário do navegador é acionado. O Svelte intercepta isso e define os valores vinculados para seus defaultValue em vez de limpá-los. Isso é especialmente útil para formulários que devem reverter para um "estado válido conhecido" em vez de ficar em branco completamente.

Prioridade na renderização inicial: Na primeira renderização, o valor da vinculação tem precedência sobre defaultValue, a menos que a vinculação seja null ou undefined. Isso significa:

<script>
	let value1 = $state('initial') // Shows "initial"
	let value2 = $state(null) // Shows "default"
</script>

<input bind:value={value1} defaultValue="default" />
<input bind:value={value2} defaultValue="default" />

Vinculações de Caixas de Seleção

Caixa de Seleção Única: `bind:checked`

Para uma única caixa de seleção, vincule a um booleano:

<script>
	let accepted = $state(false)
	let newsletter = $state(false)
	let notifications = $state(true)

	let canSubmit = $derived(accepted) // Terms must be accepted
</script>

<form>
	<label>
		<input type="checkbox" bind:checked={accepted} />
		I accept the terms and conditions (required)
	</label>

	<label>
		<input type="checkbox" bind:checked={newsletter} />
		Subscribe to newsletter (optional)
	</label>

	<label>
		<input type="checkbox" bind:checked={notifications} />
		Enable push notifications (optional)
	</label>

	<button type="submit" disabled={!canSubmit}>Submit</button>
</form>

<div class="status">
	<p>Terms accepted: {accepted ? '✓' : '✗'}</p>
	<p>Newsletter: {newsletter ? '✓' : '✗'}</p>
	<p>Notifications: {notifications ? '✓' : '✗'}</p>
</div>

Por que bind:checked e não bind:value? Para caixas de seleção, a propriedade significativa é checked (um booleano), não value (que normalmente é uma string estática como "on"). O Svelte vincula ao que importa.

Reset de formulário com defaultChecked: Semelhante ao defaultValue, as caixas de seleção podem ter um atributo defaultChecked:

<script>
	let enabled = $state(true)
</script>

<form>
	<label>
		<input type="checkbox" bind:checked={enabled} defaultChecked={true} />
		Feature enabled
	</label>

	<button type="reset">Reset to default (checked)</button>
</form>

Quando o formulário for resetado, enabled se tornará true (o padrão), não false.

Estado Indeterminado: `bind:indeterminate`

As caixas de seleção podem estar em um estado indeterminado — visualmente distinto de marcado ou desmarcado. Isso é útil para caixas de seleção "selecionar tudo" que controlam um grupo:

<script>
	let items = $state([
		{ id: 1, name: 'Item 1', selected: true },
		{ id: 2, name: 'Item 2', selected: false },
		{ id: 3, name: 'Item 3', selected: true }
	])

	let allSelected = $derived(items.every((item) => item.selected))
	let noneSelected = $derived(items.every((item) => !item.selected))
	let someSelected = $derived(!allSelected && !noneSelected)

	function toggleAll() {
		const newState = !allSelected
		items = items.map((item) => ({ ...item, selected: newState }))
	}
</script>

<label>
	<input type="checkbox" checked={allSelected} indeterminate={someSelected} onclick={toggleAll} />
	Select All
</label>

<hr />

{#each items as item}
	<label>
		<input
			type="checkbox"
			checked={item.selected}
			onchange={(e) => {
				items = items.map((i) => (i.id === item.id ? { ...i, selected: e.target.checked } : i))
			}}
		/>
		{item.name}
	</label>
{/each}

<p>Selected: {items.filter((i) => i.selected).length} of {items.length}</p>

Por que o estado indeterminado importa: Quando você tem um checkbox pai controlando checkboxes filhos, o pai deve mostrar três estados:

Marcado: Todos os filhos estão selecionados
Desmarcado: Nenhum filho está selecionado
Indeterminado: Alguns, mas não todos os filhos estão selecionados

Isso fornece ao usuário um feedback visual claro sobre o estado da seleção sem ambiguidade.

Nota técnica: O estado indeterminado é puramente visual — ele não afeta a propriedade checked. Um checkbox pode ser ao mesmo tempo checked={true} e indeterminate={true}. O estilo indeterminado (geralmente um traço) substitui visualmente a marca de verificação.

Grupos de Checkboxes: `bind:group`

Quando múltiplos checkboxes devem preencher o mesmo array, use bind:group:

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

	let features = [
		{ id: 'wifi', label: 'WiFi', price: 0 },
		{ id: 'bluetooth', label: 'Bluetooth', price: 5 },
		{ id: 'gps', label: 'GPS', price: 10 },
		{ id: '4g', label: '4G LTE', price: 15 }
	]

	let totalPrice = $derived(
		selectedFeatures.reduce((sum, id) => {
			const feature = features.find((f) => f.id === id)
			return sum + (feature?.price || 0)
		}, 0)
	)
</script>

<fieldset>
	<legend>Select Features</legend>

	{#each features as feature}
		<label>
			<input type="checkbox" bind:group={selectedFeatures} value={feature.id} />
			{feature.label}
			{#if feature.price > 0}
				(+${feature.price})
			{/if}
		</label>
	{/each}
</fieldset>

<p>Selected: {selectedFeatures.join(', ') || 'None'}</p>
<p>Additional cost: ${totalPrice}</p>

Como o bind:group funciona: Todos os checkboxes com bind:group={array} compartilham o mesmo array. Quando um checkbox é marcado, seu atributo value é adicionado ao array. Quando desmarcado, ele é removido. O Svelte cuida da manipulação do array para você.

Por que não usar booleanos individuais? Você poderia criar um booleano separado para cada checkbox, mas então precisaria acompanhar manualmente quais estão marcados e construir o array você mesmo. O bind:group elimina essa necessidade.

Importante: Todos os checkboxes em um grupo devem estar no mesmo componente Svelte. Grupos não funcionam entre fronteiras de componentes (embora você possa passar o array como prop para componentes filhos).

Grupos de Botões de Rádio

Botões de rádio são mutuamente exclusivos — apenas um pode ser selecionado por vez. Use bind:group com a mesma variável para todos os rádios do grupo:

<script>
	let shippingMethod = $state('standard')

	let shippingOptions = [
		{ id: 'standard', label: 'Standard (5-7 days)', price: 5.99 },
		{ id: 'express', label: 'Express (2-3 days)', price: 12.99 },
		{ id: 'overnight', label: 'Overnight', price: 24.99 }
	]

	let shippingCost = $derived.by(() => {
		const option = shippingOptions.find((o) => o.id === shippingMethod)
		return option?.price || 0
	})
</script>

<fieldset>
	<legend>Shipping Method</legend>

	{#each shippingOptions as option}
		<label>
			<input type="radio" bind:group={shippingMethod} value={option.id} />
			{option.label} - ${option.price.toFixed(2)}
		</label>
	{/each}
</fieldset>

<p>Selected: {shippingMethod}</p>
<p>Shipping cost: ${shippingCost.toFixed(2)}</p>

Por que usar bind:group para rádios? Ao contrário dos checkboxes (onde bind:group preenche um array), botões de rádio com bind:group definem a variável com o value do rádio selecionado. Quando você seleciona um rádio diferente, a variável é atualizada para o valor daquele rádio.

Modelo mental: Pense nos botões de rádio como um controle de "escolha uma entre estas opções". A variável do grupo armazena o valor da opção atualmente selecionada. Quando o usuário clica em um rádio diferente, o Svelte atualiza a variável. Quando você altera a variável programaticamente, o Svelte marca o rádio correspondente.

Seleção padrão: Se nenhum rádio estiver inicialmente marcado, o valor inicial da variável determina qual rádio é selecionado:

<script>
	let method = $state('express') // 'Express' radio will be checked on load
</script>

Se o valor da variável não corresponder ao value de nenhum rádio, nenhum rádio estará marcado inicialmente (embora os usuários possam selecionar um depois).

Dropdowns de Select

Select Simples: `bind:value`

O binding de um elemento <select> corresponde à propriedade value da <option> selecionada:

<script>
	let selectedCountry = $state('us')

	let countries = [
		{ code: 'us', name: 'United States' },
		{ code: 'ca', name: 'Canada' },
		{ code: 'uk', name: 'United Kingdom' },
		{ code: 'au', name: 'Australia' },
		{ code: 'de', name: 'Germany' }
	]
</script>

<label>
	Country:
	<select bind:value={selectedCountry}>
		{#each countries as country}
			<option value={country.code}>
				{country.name}
			</option>
		{/each}
	</select>
</label>

<p>You selected: {selectedCountry}</p>

Os valores de opção podem ser de qualquer tipo: Ao contrário do HTML puro (onde os valores são sempre strings), o Svelte permite usar objetos ou números como valores de opção:

<script>
	let selectedUser = $state(null)

	let users = [
		{ id: 1, name: 'Alice', role: 'Admin' },
		{ id: 2, name: 'Bob', role: 'Editor' },
		{ id: 3, name: 'Charlie', role: 'Viewer' }
	]
</script>

<select bind:value={selectedUser}>
	<option value={null}>-- Select a user --</option>
	{#each users as user}
		<option value={user}>
			{user.name} ({user.role})
		</option>
	{/each}
</select>

{#if selectedUser}
	<p>Selected: {selectedUser.name}, role: {selectedUser.role}</p>
{/if}

Quando o usuário seleciona uma opção, selectedUser se torna o objeto de usuário completo, não apenas uma string. Isso elimina a necessidade de buscas.

Seleção padrão com o atributo selected: Você pode marcar uma opção como selecionada inicialmente usando o atributo selected:

<select bind:value={color}>
	<option value="red">Red</option>
	<option value="green" selected>Green</option>
	<option value="blue">Blue</option>
</select>

Quando um formulário contendo este select for redefinido, ele voltará para "Green" (a opção marcada), não para a primeira opção.

Prioridade na renderização inicial: Assim como com inputs, o valor do binding tem precedência sobre o atributo selected, a menos que o binding seja undefined.

Select Múltiplo: `bind:value` com Array

Um elemento <select multiple> se comporta como um grupo de checkboxes — a variável vinculada é um array:

<script>
	let selectedTags = $state(['javascript', 'svelte'])

	let availableTags = [
		'javascript',
		'typescript',
		'svelte',
		'react',
		'vue',
		'angular',
		'node',
		'deno'
	]
</script>

<label>
	Select tags (hold Ctrl/Cmd to select multiple):
	<select bind:value={selectedTags} multiple size="8">
		{#each availableTags as tag}
			<option value={tag}>{tag}</option>
		{/each}
	</select>
</label>

<p>Selected: {selectedTags.join(', ') || 'None'}</p>

Como funciona: Quando uma opção é selecionada, seu valor é adicionado ao array. Quando desmarcada, ele é removido. O Svelte mantém o array sincronizado com as seleções do usuário.

Nota de usabilidade: Dropdowns de seleção múltipla são notoriamente difíceis de usar. Considere usar checkboxes ou componentes de multi-select personalizados para uma melhor experiência do usuário.

Inputs de Arquivo: `bind:files`

Inputs de arquivo usam bind:files para acessar o FileList de arquivos selecionados:

<script>
	let files = $state()
	let previewUrls = $state([])

	$effect(() => {
		if (files && files.length > 0) {
			previewUrls = Array.from(files).map((file) => URL.createObjectURL(file))
		} else {
			previewUrls = []
		}

		// Cleanup URLs when files change
		return () => {
			previewUrls.forEach((url) => URL.revokeObjectURL(url))
		}
	})

	function clearFiles() {
		// To clear files, you must create a new FileList via DataTransfer
		files = new DataTransfer().files
	}
</script>

<label for="images">Upload images:</label>
<input id="images" type="file" bind:files accept="image/*" multiple />

<button onclick={clearFiles}>Clear</button>

{#if files && files.length > 0}
	<p>Selected {files.length} file(s):</p>
	<ul>
		{#each Array.from(files) as file}
			<li>{file.name} ({(file.size / 1024).toFixed(2)} KB)</li>
		{/each}
	</ul>

	<div class="previews">
		{#each previewUrls as url}
			<img src={url} alt="Preview" style="max-width: 200px; margin: 8px;" />
		{/each}
	</div>
{/if}

Por que o bind:files é especial: Ao contrário de outros bindings, inputs de arquivo exigem um objeto FileList, que não pode ser construído diretamente. Para definir arquivos programaticamente, você deve criar um objeto DataTransfer e obter sua propriedade files.

Por que os arquivos começam como undefined: Em ambientes de renderização no lado do servidor, o DataTransfer pode não estar disponível. Deixar files não inicializado evita erros durante o SSR.

Modificando a lista de arquivos: FileList é imutável — você não pode remover arquivos individuais diretamente. Para remover um arquivo, crie um novo DataTransfer, adicione os arquivos que deseja manter e atribua o novo FileList:

<script>
	function removeFile(indexToRemove) {
		const dt = new DataTransfer()
		Array.from(files).forEach((file, index) => {
			if (index !== indexToRemove) {
				dt.items.add(file)
			}
		})
		files = dt.files
	}
</script>

Bindings de Elementos de Mídia

Elementos de mídia (<audio> e <video>) possuem várias propriedades vinculáveis. Entender quais são bidirecionais e quais são somente leitura é fundamental.

Bindings de Mídia Bidirecionais

Estas propriedades podem ser tanto lidas quanto definidas:

<script>
	let currentTime = $state(0)
	let playbackRate = $state(1)
	let paused = $state(true)
	let volume = $state(1)
	let muted = $state(false)
</script>

<video
	src="/sample-video.mp4"
	bind:currentTime
	bind:playbackRate
	bind:paused
	bind:volume
	bind:muted
	controls
></video>

<div class="controls">
	<button onclick={() => (paused = !paused)}>
		{paused ? '▶️ Play' : '⏸️ Pause'}
	</button>

	<button onclick={() => (currentTime = 0)}>⏮️ Restart</button>

	<label>
		Volume: {Math.round(volume * 100)}%
		<input type="range" bind:value={volume} min="0" max="1" step="0.01" />
	</label>

	<label>
		<input type="checkbox" bind:checked={muted} />
		Muted
	</label>

	<label>
		Speed:
		<select bind:value={playbackRate}>
			<option value={0.5}>0.5x</option>
			<option value={1}>1x (Normal)</option>
			<option value={1.25}>1.25x</option>
			<option value={1.5}>1.5x</option>
			<option value={2}>2x</option>
		</select>
	</label>
</div>

Por que estes são bidirecionais:

currentTime: Você pode buscar um momento específico definindo este valor
playbackRate: Você pode acelerar ou desacelerar a reprodução programaticamente
paused: Definir paused = false reproduz o vídeo; paused = true pausa
volume: Você pode ajustar o volume programaticamente (0 a 1)
muted: Você pode ativar/desativar o mudo programaticamente

Esses bindings permitem que você construa controles de mídia personalizados totalmente sincronizados com o estado do elemento de mídia.

Bindings de Mídia Somente Leitura

Estas propriedades refletem o estado da mídia, mas não podem ser definidas:

<script>
	let duration = $state(0)
	let buffered = $state(null)
	let seekable = $state(null)
	let seeking = $state(false)
	let ended = $state(false)
	let readyState = $state(0)
	let played = $state(null)

	let progress = $derived(duration > 0 ? (currentTime / duration) * 100 : 0)
</script>

<audio
	src="/podcast.mp3"
	bind:duration
	bind:buffered
	bind:seekable
	bind:seeking
	bind:ended
	bind:readyState
	bind:played
	controls
></audio>

<div class="info">
	<p>Duration: {Math.floor(duration)}s</p>
	<p>Progress: {progress.toFixed(1)}%</p>
	<p>Ready state: {readyState} (0-4)</p>
	<p>Seeking: {seeking ? 'Yes' : 'No'}</p>
	<p>Ended: {ended ? 'Yes' : 'No'}</p>
</div>

Por que estes são somente leitura:

duration: A duração da mídia é determinada pelo próprio arquivo
buffered: O buffering é gerenciado pelo navegador, não pelo seu código
seekable: Quais intervalos são navegáveis depende do formato da mídia
seeking: Reflete se uma operação de busca está em andamento
ended: Verdadeiro quando a reprodução chegou ao fim
readyState: Acompanha o estado de carregamento (0 = nada, 4 = carregado o suficiente)
played: TimeRanges representando quais partes foram reproduzidas

Esses bindings são úteis para exibir informações ou reagir a mudanças de estado (via $effect), mas você não pode alterar a mídia definindo-os.

Bindings Específicos de Vídeo

Elementos de vídeo têm dois bindings somente leitura adicionais para dimensões:

<script>
	let videoWidth = $state(0)
	let videoHeight = $state(0)
</script>

<video src="/movie.mp4" bind:videoWidth bind:videoHeight controls></video>

<p>Video dimensions: {videoWidth} × {videoHeight}</p>

Por que somente leitura? As dimensões intrínsecas do vídeo vêm do próprio arquivo de vídeo. Você pode estilizar o elemento <video> com CSS para exibi-lo em qualquer tamanho, mas a resolução real do vídeo é fixa.

Bindings de Elemento de Imagem

Imagens possuem bindings somente leitura similares para suas dimensões naturais (intrínsecas):

<script>
	let naturalWidth = $state(0)
	let naturalHeight = $state(0)
</script>

<img src="/photo.jpg" bind:naturalWidth bind:naturalHeight alt="Sample" style="max-width: 400px;" />

<p>Original image size: {naturalWidth} × {naturalHeight}</p>
<p>Display size: {naturalWidth > 400 ? '400px (scaled)' : naturalWidth + 'px'}</p>

Caso de uso: Esses bindings são úteis para o tratamento responsivo de imagens, cálculo de proporções ou validação das dimensões da imagem antes do upload.

Elemento Details: `bind:open`

O elemento <details> tem uma ligação bidirecional open:

<script>
	let detailsOpen = $state(false)
	let faqOpen = $state(false)
</script>

<details bind:open={detailsOpen}>
	<summary>What is Svelte?</summary>
	<p>Svelte is a radical new approach to building user interfaces...</p>
</details>

<details bind:open={faqOpen}>
	<summary>How does binding work?</summary>
	<p>Bindings create a two-way connection between state and DOM properties...</p>
</details>

<button onclick={() => (detailsOpen = !detailsOpen)}>
	{detailsOpen ? 'Collapse' : 'Expand'} first section
</button>

<button
	onclick={() => {
		detailsOpen = true
		faqOpen = true
	}}
>
	Expand all
</button>

<button
	onclick={() => {
		detailsOpen = false
		faqOpen = false
	}}
>
	Collapse all
</button>

Por que isso é útil: Você pode controlar widgets de divulgação programaticamente, criar funcionalidade "expandir tudo" ou persistir o estado aberto/fechado no localStorage.

Ligações Contenteditable

Elementos com contenteditable="true" podem se ligar a três propriedades de texto diferentes:

<script>
	let htmlContent = $state('<p><strong>Bold</strong> and <em>italic</em> text</p>')
	let innerTextContent = $state('Plain text only')
	let textContentValue = $state('Raw text content')
</script>

<div class="editor-section">
	<h3>innerHTML (preserves HTML tags)</h3>
	<div contenteditable="true" bind:innerHTML={htmlContent} class="editor"></div>
	<pre>{htmlContent}</pre>
</div>

<div class="editor-section">
	<h3>innerText (respects text rendering)</h3>
	<div contenteditable="true" bind:innerText={innerTextContent} class="editor"></div>
	<pre>{innerTextContent}</pre>
</div>

<div class="editor-section">
	<h3>textContent (raw text nodes)</h3>
	<div contenteditable="true" bind:textContent={textContentValue} class="editor"></div>
	<pre>{textContentValue}</pre>
</div>

<style>
	.editor {
		border: 1px solid #ccc;
		padding: 12px;
		min-height: 100px;
		border-radius: 4px;
		margin-bottom: 8px;
	}

	.editor:focus {
		outline: 2px solid #0066cc;
	}
</style>

Diferenças explicadas:

innerHTML: Inclui todas as tags HTML. Útil para editores de texto rico, mas perigoso com entrada do usuário (risco de XSS)
innerText: Respeita o estilo CSS e a visibilidade. Texto oculto é excluído, <br> vira quebra de linha
textContent: Conteúdo de texto bruto de todos os nós. Inclui texto oculto, ignora estilização

Aviso de segurança: Usar bind:innerHTML com conteúdo gerado pelo usuário expõe você a ataques XSS. Sempre sanitize o HTML antes de renderizar:

<script>
	import DOMPurify from 'dompurify'

	let userHtml = $state('')
	let sanitizedHtml = $derived(DOMPurify.sanitize(userHtml))
</script>

<div contenteditable bind:innerHTML={userHtml}></div><div>{@html sanitizedHtml}</div>

Ligações de Dimensão (Somente Leitura)

Todos os elementos visíveis podem se ligar às suas dimensões usando um ResizeObserver. Essas ligações são somente leitura—você não pode redimensionar um elemento definindo esses valores:

<script>
	let clientWidth = $state(0)
	let clientHeight = $state(0)
	let offsetWidth = $state(0)
	let offsetHeight = $state(0)
	let contentRect = $state(null)

	let area = $derived(clientWidth * clientHeight)
</script>

<div
	class="measured-box"
	bind:clientWidth
	bind:clientHeight
	bind:offsetWidth
	bind:offsetHeight
	bind:contentRect
>
	<p>Resize your browser window to see measurements update</p>
	<p>clientWidth: {clientWidth}px (content + padding)</p>
	<p>clientHeight: {clientHeight}px</p>
	<p>offsetWidth: {offsetWidth}px (content + padding + border + scrollbar)</p>
	<p>offsetHeight: {offsetHeight}px</p>
	<p>Area: {area.toLocaleString()}px²</p>
</div>

<style>
	.measured-box {
		border: 5px solid #333;
		padding: 20px;
		margin: 20px;
		background: #f0f0f0;
		resize: both;
		overflow: auto;
		min-width: 200px;
		min-height: 150px;
	}
</style>

Entendendo as dimensões:

clientWidth/Height: Área de conteúdo + padding (exclui borda e barra de rolagem)
offsetWidth/Height: Área de conteúdo + padding + borda + barra de rolagem
contentRect: Um DOMRectReadOnly com medições mais detalhadas
contentBoxSize: Array de objetos ResizeObserverSize
borderBoxSize: Similar, mas inclui a borda
devicePixelContentBoxSize: Dimensões em pixels físicos (útil para displays de alta densidade)

Por que somente leitura? Essas ligações observam o tamanho do elemento conforme determinado pelo layout, CSS e conteúdo. Você não pode forçar um elemento a ter um tamanho específico definindo esses valores—você deve usar CSS ou o atributo style.

Casos de uso:

Dimensionamento responsivo de canvas
Dimensões dinâmicas de gráficos
Renderização condicional baseada no tamanho do contêiner
Medição de texto ou conteúdo antes de decisões de layout

Nota de desempenho: As ligações de dimensão usam ResizeObserver, que é altamente eficiente. No entanto, evite ligar dimensões a centenas de elementos simultaneamente—considere usar uma lista virtualizada ou medir um contêiner em vez disso.

Ressalva importante: Elementos com display: inline não têm largura/altura (exceto elementos de tamanho intrínseco como <img> e <canvas>). Altere o display do elemento para inline-block ou block para medi-lo.

Referências de Elementos: bind:this

A diretiva bind:this captura uma referência a um elemento DOM ou instância de componente:

<script>
	let inputRef = $state(null)
	let canvasRef = $state(null)

	function focusInput() {
		inputRef?.focus()
	}

	$effect(() => {
		if (canvasRef) {
			const ctx = canvasRef.getContext('2d')
			ctx.fillStyle = '#ff0000'
			ctx.fillRect(10, 10, 100, 100)
		}
	})
</script>

<input bind:this={inputRef} placeholder="Click button to focus me" />
<button onclick={focusInput}>Focus Input</button>

<canvas bind:this={canvasRef} width="200" height="200"></canvas>

Quando usar bind:this:

Chamar APIs imperativas do DOM (focus, play, pause, select)
Medir elementos que não possuem dimensões vinculáveis
Integrar bibliotecas de terceiros que precisam de uma referência DOM
Acessar elementos de formulário para validação

Timing do ciclo de vida: A referência é undefined até o elemento ser montado. Sempre use encadeamento opcional (?.) ou verifique a existência:

<script>
	let videoRef = $state(null)

	function playVideo() {
		if (videoRef) {
			videoRef.play()
		}
	}

	// AVOID: This runs during initialization, before mount
	// videoRef.play() // Error: videoRef is undefined

	// PREFERRED: Use $effect or event handlers
	$effect(() => {
		videoRef?.play()
	})
</script>

Referências de Instâncias de Componentes

Você também pode se ligar a instâncias de componentes para chamar suas funções exportadas. Embora o Svelte 5 incentive padrões declarativos, APIs imperativas ainda são úteis para determinados cenários como modais e animações.

Abordagem Imperativa (usando `bind:this`):

<!-- Modal.svelte -->
<script>
	let { children } = $props()
	let isOpen = $state(false)

	// Functions accessible via bind:this
	function open() {
		isOpen = true
	}

	function close() {
		isOpen = false
	}

	function toggle() {
		isOpen = !isOpen
	}

	// Export functions so parent can call them via bind:this
	export { open, close, toggle }
</script>

{#if isOpen}
	<div class="modal-backdrop" onclick={close}>
		<div class="modal-content" onclick={(e) => e.stopPropagation()}>
			{@render children()}
			<button onclick={close}>Close</button>
		</div>
	</div>
{/if}

<!-- Parent.svelte -->
<script>
	import Modal from './Modal.svelte'

	let modalRef = $state(null)
</script>

<button onclick={() => modalRef?.open()}>Open Modal</button>
<button onclick={() => modalRef?.toggle()}>Toggle Modal</button>

<Modal bind:this={modalRef}>
	<h2>Modal Content</h2>
	<p>This modal was opened programmatically!</p>
</Modal>

Embora isso funcione, mistura controle imperativo com renderização declarativa, o que pode levar a código mais difícil de manter. No Svelte 5, prefira usar props $bindable para maior clareza e testabilidade.

Abordagem Declarativa (preferida no Svelte 5):

<!-- Modal.svelte -->
<script>
	let { open = $bindable(false), children } = $props()

	function close() {
		open = false
	}
</script>

{#if open}
	<div class="modal-backdrop" onclick={close}>
		<div class="modal-content" onclick={(e) => e.stopPropagation()}>
			{@render children()}
			<button onclick={close}>Close</button>
		</div>
	</div>
{/if}

<!-- Parent.svelte -->
<script>
	import Modal from './Modal.svelte'

	let isModalOpen = $state(false)
</script>

<button onclick={() => (isModalOpen = true)}>Open Modal</button>
<button onclick={() => (isModalOpen = !isModalOpen)}>Toggle Modal</button>

<Modal bind:open={isModalOpen}>
	<h2>Modal Content</h2>
	<p>This modal is controlled declaratively!</p>
</Modal>

Com o uso da diretiva $bindable para a prop open, o componente pai gerencia o estado de abertura do modal de forma reativa. Isso leva a um fluxo de dados mais claro e facilita os testes.

Quando usar cada abordagem?

Cada abordagem tem seus méritos, e entender as trocas ajuda você a escolher o padrão certo para o seu caso de uso. A decisão geralmente se resume ao fluxo de controle: quem deve ser dono do estado e quão complexo é o comportamento do componente?

Use imperativo (bind:this):

Animações ou transições complexas - Quando você precisa de controle detalhado sobre o tempo de animação, sequenciamento ou coordenação entre múltiplos elementos. Por exemplo, um carrossel que precisa pausar, retomar ou saltar para slides específicos programaticamente.
Integração com bibliotecas de terceiros - Ao encapsular componentes de bibliotecas que expõem APIs imperativas (como bibliotecas de gráficos com métodos .update() ou .destroy()).
Múltiplas ações não relacionadas - Quando um componente expõe várias operações independentes que não se mapeiam para um único valor de estado. Por exemplo, um player de vídeo com play(), pause(), seek(), setPlaybackRate() e captureFrame().
Testar internos de componentes - Quando você precisa acessar estado interno ou acionar comportamentos específicos durante testes unitários, embora isso deva ser usado com moderação.
Componentes legados ou de terceiros - Ao trabalhar com componentes existentes que foram projetados com APIs imperativas e refatorá-los não é prático.

Use declarativo (props $bindable):

Gerenciamento simples de estado - Quando o comportamento do componente se mapeia claramente para um booleano ou valor simples (aberto/fechado, visível/oculto, valor selecionado).
Estado controlado pelo pai - Quando o componente pai precisa ser a fonte de verdade para o estado, tornando mais fácil coordenar com outras partes da sua aplicação.
Fluxo de dados previsível - Quando você quer mudanças de estado explícitas e rastreáveis que são mais fáceis de depurar e compreender. Cada mudança de estado flui pelo sistema reativo do pai.
Melhor testabilidade - Quando você quer testar o componente simplesmente passando diferentes valores de prop em vez de chamar métodos e verificar efeitos colaterais.
Filosofia do Svelte 5 - A abordagem declarativa está alinhada com o movimento do Svelte 5 em direção a padrões mais reativos e menos imperativos. É mais fácil de entender e manter ao longo do tempo.

Abordagem híbrida

Para componentes complexos, você pode combinar ambos os padrões:

<!-- VideoPlayer.svelte -->
<script>
	let { playing = $bindable(false), volume = $bindable(0.8), currentTime = $bindable(0) } = $props()

	let videoElement = $state(null)

	// Imperative methods for complex operations
	function captureFrame() {
		const canvas = document.createElement('canvas')
		const ctx = canvas.getContext('2d')
		canvas.width = videoElement.videoWidth
		canvas.height = videoElement.videoHeight
		ctx.drawImage(videoElement, 0, 0)
		return canvas.toDataURL('image/png')
	}

	function skipToChapter(chapterIndex) {
		currentTime = chapters[chapterIndex].startTime
	}

	export { captureFrame, skipToChapter }
</script>

<video bind:this={videoElement} bind:paused={!playing} bind:volume bind:currentTime />

Boas práticas: Comece com a abordagem declarativa usando props $bindable. Adicione métodos imperativos via bind:this somente quando encontrar operações que genuinamente não se mapeiam para estado reativo. A maioria dos componentes de modal, dropdown e toggle deve ser totalmente declarativa.

Ligações de Props de Componentes com `$bindable`

O Svelte 5 apresenta a rune $bindable para ligação bidirecional entre componentes pai e filho.

Tornando Props Vinculáveis

No componente filho, marque as props como $bindable:

<!-- Counter.svelte -->
<script>
	let { count = $bindable(0), step = 1 } = $props()
</script>

<div class="counter">
	<button onclick={() => (count -= step)}>−</button>
	<span>{count}</span>
	<button onclick={() => (count += step)}>+</button>
</div>

No pai, use bind: para estabelecer a ligação bidirecional:

<!-- Parent.svelte -->
<script>
	import Counter from './Counter.svelte'

	let value = $state(10)
</script>

<Counter bind:count={value} step={5} />

<p>Value in parent: {value}</p>

<button onclick={() => (value = 0)}>Reset from parent</button>

Como funciona: Quando o componente filho atualiza count, o value do pai é atualizado automaticamente. Quando o pai atualiza value, a exibição do filho é atualizada. Esta é uma ligação bidirecional verdadeira entre fronteiras de componentes.

Valores de fallback: Props vinculáveis podem ter valores padrão:

<script>
	let { count = $bindable(0) } = $props()
</script>

O valor de fallback (0) se aplica quando o pai não vincula a prop. Se o pai vincular a prop mas passar undefined, você receberá um erro em tempo de execução:

<!-- AVOID: This throws an error -->
<Counter bind:count={undefinedValue} />

<!-- PREFERRED: This works -->
<Counter bind:count={zeroValue} />
<Counter />
<!-- Uses fallback: 0 -->

Por que o erro? O Svelte impõe que, se você optar pela vinculação, deve fornecer um valor definido. Isso evita situações confusas onde o valor de fallback entra em conflito com uma vinculação indefinida.

Múltiplas Props Vinculáveis

Componentes podem ter múltiplas props $bindable:

<!-- RangeSlider.svelte -->
<script>
	let { min = $bindable(0), max = $bindable(100), step = 1 } = $props()

	// Ensure min < max
	$effect(() => {
		if (min > max) {
			max = min
		}
	})
</script>

<div class="range-slider">
	<label>
		Min: {min}
		<input type="range" bind:value={min} min="0" max="100" {step} />
	</label>

	<label>
		Max: {max}
		<input type="range" bind:value={max} {min} max="100" {step} />
	</label>
</div>

Uso:

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

	let minPrice = $state(20)
	let maxPrice = $state(80)
</script>

<RangeSlider bind:min={minPrice} bind:max={maxPrice} step={5} />

<p>Price range: ${minPrice} - ${maxPrice}</p>

Componentes de Input Personalizados

Crie componentes de formulário reutilizáveis com validação e estilização:

<!-- TextField.svelte -->
<script>
	let {
		value = $bindable(''),
		label,
		type = 'text',
		placeholder = '',
		error = '',
		required = false
	} = $props()

	let touched = $state(false)
	let showError = $derived(touched && error)
</script>

<div class="text-field">
	<label>
		{label}
		{#if required}<span class="required">*</span>{/if}
		<input
			{type}
			bind:value
			{placeholder}
			class:error={showError}
			onblur={() => (touched = true)}
		/>
	</label>
	{#if showError}
		<p class="error-message">{error}</p>
	{/if}
</div>

<style>
	.text-field {
		margin-bottom: 16px;
	}

	label {
		display: block;
		font-weight: 500;
		margin-bottom: 4px;
	}

	.required {
		color: #dc2626;
	}

	input {
		width: 100%;
		padding: 8px 12px;
		border: 1px solid #ccc;
		border-radius: 4px;
		font-size: 16px;
	}

	input:focus {
		outline: none;
		border-color: #0066cc;
	}

	input.error {
		border-color: #dc2626;
	}

	.error-message {
		color: #dc2626;
		font-size: 14px;
		margin: 4px 0 0;
	}
</style>

Uso com validação:

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

	let formData = $state({
		email: '',
		password: '',
		confirmPassword: ''
	})

	let errors = $derived.by(() => {
		let errs = {}

		if (formData.email && !/\S+@\S+\.\S+/.test(formData.email)) {
			errs.email = 'Please enter a valid email address'
		}

		if (formData.password && formData.password.length < 8) {
			errs.password = 'Password must be at least 8 characters'
		}

		if (formData.confirmPassword && formData.password !== formData.confirmPassword) {
			errs.confirmPassword = 'Passwords do not match'
		}

		return errs
	})
</script>

<form>
	<TextField
		bind:value={formData.email}
		label="Email"
		type="email"
		placeholder="you@example.com"
		error={errors.email}
		required
	/>

	<TextField
		bind:value={formData.password}
		label="Password"
		type="password"
		error={errors.password}
		required
	/>

	<TextField
		bind:value={formData.confirmPassword}
		label="Confirm Password"
		type="password"
		error={errors.confirmPassword}
		required
	/>

	<button type="submit" disabled={Object.keys(errors).length > 0}> Create Account </button>
</form>

Bindings de Função (Avançado)

Desde o Svelte 5.9, você pode usar bindings de função com a sintaxe bind:property={get, set}. Isso permite interceptar e transformar valores:

<script>
	let value = $state('HELLO')
</script>

<!-- Two-way binding with transformation -->
<input bind:value={() => value, (v) => (value = v.toUpperCase())} />

<p>Value (always uppercase): {value}</p>

Como funciona: A primeira função (getter) retorna o valor atual para exibição. A segunda função (setter) recebe o novo valor e pode transformá-lo antes de atribuir.

Casos de uso:

Normalização de input (trim, maiúsculas, formatação)
Validação antes de aceitar valores
Bindings computados com efeitos colaterais

Para bindings somente leitura: Use null como getter:

<script>
	let width = $state(0)

	function handleResize(newWidth) {
		console.log('Width changed to:', newWidth)
		width = newWidth
	}
</script>

<div bind:clientWidth={null, handleResize}>Resizable element</div>

Isso é útil quando você quer reagir a mudanças de dimensão, mas não precisa exibir o valor diretamente.

Problemas Comuns e Soluções

1: Binding com Valores Derivados

Problema: Você não pode fazer binding diretamente com valores $derived, pois eles são valores computados somente leitura.

<script>
	let firstName = $state('John')
	let lastName = $state('Doe')

	let fullName = $derived(`${firstName} ${lastName}`)
</script>

<!-- AVOID: Cannot bind to derived value -->
<input bind:value={fullName} />

Solução 1: Faça binding com as variáveis de estado subjacentes:

<input bind:value={firstName} placeholder="First name" />
<input bind:value={lastName} placeholder="Last name" />
<p>Full name: {fullName}</p>

Solução 2: Use a sintaxe de binding de função do Svelte 5.9 para fazer binding de uma leitura derivada com um setter explícito:

<script>
	let celsius = $state(0)

	// Derived for display
	let fahrenheit = $derived((celsius * 9) / 5 + 32)
</script>

<label>
	Celsius: <input type="number" bind:value={celsius} />
</label>
<label>
	Fahrenheit:
	<!-- getter returns derived, setter writes back through celsius -->
	<input type="number" bind:value={() => fahrenheit, (f) => (celsius = ((f - 32) * 5) / 9)} />
</label>

2: Inputs Numéricos Tornando-se `undefined`

Problema: Inputs numéricos vazios ou inválidos tornam-se undefined, o que pode quebrar cálculos.

<script>
	let quantity = $state(0)
	let price = $state(0)

	// AVOID: If either is undefined, total is NaN
	let total = $derived(quantity * price)
</script>

Solução: Use coalescência nula ou verificações explícitas:

<script>
	let quantity = $state(0)
	let price = $state(0)

	let total = $derived((quantity ?? 0) * (price ?? 0))
	// Or: isNaN(quantity) || isNaN(price) ? 0 : quantity * price
</script>

3: Binding com Propriedades de Array/Objeto

Problema: Mutação direta não dispara reatividade no Svelte 5.

<script>
	let items = $state([
		{ id: 1, name: 'Item 1', checked: false },
		{ id: 2, name: 'Item 2', checked: false }
	])
</script>

<!-- AVOID: Direct mutation -->
<input
	type="checkbox"
	checked={items[0].checked}
	onchange={(e) => (items[0].checked = e.target.checked)}
/>

Solução: Crie um novo array para disparar reatividade:

<input
	type="checkbox"
	checked={items[0].checked}
	onchange={(e) => {
		items = items.map((item, i) => (i === 0 ? { ...item, checked: e.target.checked } : item))
	}}
/>

Abordagem melhor: Use bind:checked com um handler que atualiza o estado corretamente:

{#each items as item, i}
	<label>
		<input
			type="checkbox"
			checked={item.checked}
			onchange={(e) => {
				// $state Proxy tracks property mutations automatically
				items[i].checked = e.target.checked
			}}
		/>
		{item.name}
	</label>
{/each}

4: Binding Sem `$bindable`

Problema: Tentar fazer binding com uma prop de componente que não está marcada como $bindable.

<!-- AVOID: Child component without $bindable -->
<script>
	let { value } = $props() // Not bindable!
</script>

<!-- AVOID: Parent tries to bind - THIS FAILS -->
<Child bind:value={parentValue} />

Solução: Marque a prop como $bindable no componente filho:

<!-- PREFERRED: Child component with $bindable -->
<script>
	let { value = $bindable(0) } = $props()
</script>

<!-- PREFERRED: Now this works -->
<Child bind:value={parentValue} />

5: Grupo de Checkboxes vs. Booleanos Individuais

Problema: Usar o mesmo booleano para múltiplos checkboxes faz com que eles se comportem de forma idêntica.

<script>
	let agreed = $state(false)
</script>

<!-- AVOID: Both checkboxes control the same boolean -->
<label><input type="checkbox" bind:checked={agreed} /> Terms</label>
<label><input type="checkbox" bind:checked={agreed} /> Privacy</label>
<!-- Checking one checks both! -->

Solução: Use bind:group para arrays ou booleanos separados:

<script>
	// Option 1: bind:group with array
	let agreements = $state([])
</script>

<label><input type="checkbox" bind:group={agreements} value="terms" /> Terms</label>
<label><input type="checkbox" bind:group={agreements} value="privacy" /> Privacy</label>

<!-- Option 2: Separate booleans -->
<script>
	let agreedTerms = $state(false)
	let agreedPrivacy = $state(false)
</script>

<label><input type="checkbox" bind:checked={agreedTerms} /> Terms</label>
<label><input type="checkbox" bind:checked={agreedPrivacy} /> Privacy</label>

6: Select Não Exibindo o Valor Inicial

Problema: O dropdown de select não exibe o valor vinculado na renderização inicial.

<script>
	let selectedColor = $state('purple') // No matching option!
</script>

<select bind:value={selectedColor}>
	<option value="red">Red</option>
	<option value="green">Green</option>
	<option value="blue">Blue</option>
</select>
<!-- Shows blank because "purple" doesn't exist -->

Solução: Certifique-se de que o valor inicial corresponde a uma opção, ou forneça um placeholder:

<script>
	let selectedColor = $state('red') // Matches first option
</script>

<select bind:value={selectedColor}>
	<option value="">-- Select a color --</option>
	<option value="red">Red</option>
	<option value="green">Green</option>
	<option value="blue">Blue</option>
</select>

Padrões do Mundo Real

1. Input de Busca com Debounce

O Problema: Quando usuários digitam em uma caixa de busca conectada a uma API, fazer uma requisição a cada tecla pressionada sobrecarrega seu servidor. Um usuário digitando "svelte" dispara 6 chamadas de API — uma para cada letra. Isso causa carga desnecessária no servidor, desperdício de banda e possíveis condições de corrida.

A Solução: O debounce atrasa a chamada de API até que o usuário pause a digitação, reduzindo as requisições de 6 para 1 e mantendo uma UX responsiva.

<script>
	let searchQuery = $state('')
	let debouncedQuery = $state('')
	let results = $state([])
	let isSearching = $state(false)
	let debounceTimer

	// Debounce the search query
	$effect(() => {
		clearTimeout(debounceTimer)
		isSearching = true

		debounceTimer = setTimeout(() => {
			debouncedQuery = searchQuery
		}, 300)

		return () => clearTimeout(debounceTimer)
	})

	// Perform search when debounced query changes
	$effect(() => {
		if (debouncedQuery.length < 2) {
			results = []
			isSearching = false
			return
		}

		isSearching = true

		fetch(`/api/search?q=${encodeURIComponent(debouncedQuery)}`)
			.then((r) => r.json())
			.then((data) => {
				results = data
				isSearching = false
			})
			.catch(() => {
				results = []
				isSearching = false
			})
	})
</script>

<div class="search-container">
	<input
		type="search"
		bind:value={searchQuery}
		placeholder="Search products..."
		class="search-input"
	/>

	{#if isSearching}
		<div class="loading">Searching...</div>
	{:else if searchQuery.length > 0}
		{#if results.length > 0}
			<ul class="results-list">
				{#each results as result}
					<li><a href="/product/{result.id}">{result.name}</a></li>
				{/each}
			</ul>
		{:else if searchQuery.length >= 2}
			<div class="no-results">No results found for "{searchQuery}"</div>
		{/if}
	{/if}
</div>

<style>
	.search-container {
		position: relative;
		max-width: 500px;
	}

	.search-input {
		width: 100%;
		padding: 12px;
		font-size: 16px;
		border: 2px solid #ccc;
		border-radius: 8px;
	}

	.results-list {
		position: absolute;
		top: 100%;
		left: 0;
		right: 0;
		margin-top: 4px;
		background: white;
		border: 1px solid #ccc;
		border-radius: 8px;
		max-height: 300px;
		overflow-y: auto;
		box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
		list-style: none;
		padding: 0;
	}

	.results-list li {
		padding: 12px;
		border-bottom: 1px solid #eee;
	}

	.results-list li:hover {
		background: #f5f5f5;
	}

	.loading,
	.no-results {
		padding: 12px;
		text-align: center;
		color: #666;
	}
</style>

Como funciona passo a passo:

searchQuery faz binding diretamente ao input para feedback visual instantâneo
$effect observa searchQuery e define um timeout de 300ms para atualizar debouncedQuery
Se o usuário digitar novamente, o timeout antigo é cancelado e um novo é iniciado
A função de limpeza previne vazamentos de memória ao desmontar
Um $effect separado observa debouncedQuery e dispara a chamada de API
O estado isSearching fornece feedback de carregamento

Técnicas-chave: bind:value para feedback imediato, limpeza de $effect para gerenciamento de timers, estado de busca separado do estado com debounce, validação de comprimento mínimo de consulta.

Variações: Atrasos adaptativos baseados no comprimento da consulta, AbortController para cancelamento de requisições, cache de resultados, autocomplete a partir de buscas recentes.

2. Painel de Configurações com Sincronização via localStorage

O Problema: Os usuários personalizam configurações (tema, tamanho da fonte, notificações), mas tudo é redefinido ao atualizar a página, forçando uma reconfiguração a cada sessão.

A Solução: Persistir no localStorage, carregar na montagem, salvar a cada alteração e aplicar as configurações ao DOM imediatamente.

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

	let settings = $state({
		theme: 'light',
		fontSize: 16,
		notifications: true,
		autoSave: true,
		language: 'en'
	})

	// Load from localStorage on mount
	if (browser) {
		const saved = localStorage.getItem('app-settings')
		if (saved) {
			try {
				settings = { ...settings, ...JSON.parse(saved) }
			} catch (e) {
				console.error('Failed to parse saved settings')
			}
		}
	}

	// Save to localStorage whenever settings change
	$effect(() => {
		if (browser) {
			localStorage.setItem('app-settings', JSON.stringify(settings))

			// Apply theme
			document.documentElement.setAttribute('data-theme', settings.theme)
			document.documentElement.style.fontSize = `${settings.fontSize}px`
		}
	})
</script>

<div class="settings-panel">
	<h2>Settings</h2>

	<div class="setting">
		<label>
			Theme
			<select bind:value={settings.theme}>
				<option value="light">Light</option>
				<option value="dark">Dark</option>
				<option value="auto">Auto</option>
			</select>
		</label>
	</div>

	<div class="setting">
		<label>
			Font Size: {settings.fontSize}px
			<input type="range" bind:value={settings.fontSize} min="12" max="24" />
		</label>
	</div>

	<div class="setting">
		<label>
			<input type="checkbox" bind:checked={settings.notifications} />
			Enable notifications
		</label>
	</div>

	<div class="setting">
		<label>
			<input type="checkbox" bind:checked={settings.autoSave} />
			Auto-save changes
		</label>
	</div>

	<div class="setting">
		<label>
			Language
			<select bind:value={settings.language}>
				<option value="en">English</option>
				<option value="es">Español</option>
				<option value="fr">Français</option>
				<option value="de">Deutsch</option>
			</select>
		</label>
	</div>
</div>

<div class="preview">
	<p>This text respects your font size setting</p>
</div>

<style>
	.settings-panel {
		max-width: 500px;
		padding: 24px;
		background: var(--bg-secondary);
		border-radius: 8px;
	}

	.setting {
		margin-bottom: 20px;
	}

	label {
		display: block;
		font-weight: 500;
	}

	select,
	input[type='range'] {
		width: 100%;
		margin-top: 8px;
	}

	.preview {
		margin-top: 24px;
		padding: 20px;
		background: var(--bg-primary);
		border-radius: 8px;
	}
</style>

Como funciona passo a passo:

Inicializar as configurações com valores padrão em $state
Carregar do localStorage na montagem, mesclar com os padrões
$effect monitora o objeto de configurações e salva no localStorage
O mesmo $effect aplica as configurações ao DOM (tema, tamanho da fonte)
Verificar o contexto browser para compatibilidade com SSR
Try-catch em torno da análise de JSON trata corrupção de dados

Técnicas-chave: Combinação de bind:value/bind:checked para diferentes entradas, $effect para persistência dual + aplicação, verificações de browser para SSR, espalhamento de objetos para mesclagem parcial de dados.

Considerações de produção: Estratégia de migração para novas configurações, validação contra esquema, monitoramento de cota de armazenamento, sincronização entre abas via evento storage, conformidade com LGPD/GDPR.

Variações: Sincronização com backend para múltiplos dispositivos, importação/exportação como JSON, predefinições de configurações, prévia em tempo real, abas categorizadas.

3. Formulário de Múltiplas Etapas com Validação

O Problema: Formulários longos sobrecarregam os usuários. Eles precisam de indicação de progresso, capacidade de revisar etapas anteriores, feedback de validação e confiança de que seus dados não serão perdidos.

A Solução: Padrão wizard com etapas lógicas, validação independente por etapa, progresso visual, navegação para frente somente quando válido, navegação para trás sem restrições.

<script>
	let currentStep = $state(1)
	let formData = $state({
		// Step 1: Personal
		firstName: '',
		lastName: '',
		email: '',
		// Step 2: Address
		street: '',
		city: '',
		zipCode: '',
		country: 'us',
		// Step 3: Preferences
		newsletter: false,
		notifications: true,
		theme: 'light'
	})

	let step1Valid = $derived(
		formData.firstName.length > 0 &&
			formData.lastName.length > 0 &&
			/\S+@\S+\.\S+/.test(formData.email)
	)

	let step2Valid = $derived(
		formData.street.length > 0 && formData.city.length > 0 && /^\d{5}$/.test(formData.zipCode)
	)

	let canProceed = $derived(currentStep === 1 ? step1Valid : currentStep === 2 ? step2Valid : true)

	function nextStep() {
		if (currentStep < 3) currentStep++
	}

	function prevStep() {
		if (currentStep > 1) currentStep--
	}

	function handleSubmit(e) {
		e.preventDefault()
		console.log('Form submitted:', formData)
	}
</script>

<div class="wizard">
	<div class="progress">
		<div class="step" class:active={currentStep === 1} class:complete={currentStep > 1}>
			<span class="step-number">1</span>
			<span class="step-label">Personal</span>
		</div>
		<div class="step" class:active={currentStep === 2} class:complete={currentStep > 2}>
			<span class="step-number">2</span>
			<span class="step-label">Address</span>
		</div>
		<div class="step" class:active={currentStep === 3}>
			<span class="step-number">3</span>
			<span class="step-label">Preferences</span>
		</div>
	</div>

	<form onsubmit={handleSubmit}>
		{#if currentStep === 1}
			<div class="form-section">
				<h2>Personal Information</h2>
				<input bind:value={formData.firstName} placeholder="First Name" required />
				<input bind:value={formData.lastName} placeholder="Last Name" required />
				<input bind:value={formData.email} type="email" placeholder="Email" required />
			</div>
		{:else if currentStep === 2}
			<div class="form-section">
				<h2>Address</h2>
				<input bind:value={formData.street} placeholder="Street Address" required />
				<input bind:value={formData.city} placeholder="City" required />
				<input bind:value={formData.zipCode} placeholder="ZIP Code" pattern="\d{5}" required />
				<select bind:value={formData.country}>
					<option value="us">United States</option>
					<option value="ca">Canada</option>
					<option value="uk">United Kingdom</option>
				</select>
			</div>
		{:else}
			<div class="form-section">
				<h2>Preferences</h2>
				<label>
					<input type="checkbox" bind:checked={formData.newsletter} />
					Subscribe to newsletter
				</label>
				<label>
					<input type="checkbox" bind:checked={formData.notifications} />
					Enable notifications
				</label>
				<label>
					Theme:
					<select bind:value={formData.theme}>
						<option value="light">Light</option>
						<option value="dark">Dark</option>
						<option value="auto">Auto</option>
					</select>
				</label>
			</div>
		{/if}

		<div class="actions">
			{#if currentStep > 1}
				<button type="button" onclick={prevStep}>← Back</button>
			{/if}
			{#if currentStep < 3}
				<button type="button" onclick={nextStep} disabled={!canProceed}> Next → </button>
			{:else}
				<button type="submit">Complete</button>
			{/if}
		</div>
	</form>
</div>

<style>
	.wizard {
		max-width: 600px;
		margin: 0 auto;
	}

	.progress {
		display: flex;
		justify-content: space-between;
		margin-bottom: 32px;
	}

	.step {
		display: flex;
		flex-direction: column;
		align-items: center;
		flex: 1;
		position: relative;
	}

	.step:not(:last-child)::after {
		content: '';
		position: absolute;
		top: 20px;
		left: 50%;
		width: 100%;
		height: 2px;
		background: #e5e5e5;
		z-index: -1;
	}

	.step.complete::after {
		background: #16a34a;
	}

	.step-number {
		width: 40px;
		height: 40px;
		border-radius: 50%;
		display: flex;
		align-items: center;
		justify-content: center;
		background: #e5e5e5;
		font-weight: bold;
		margin-bottom: 8px;
	}

	.step.active .step-number {
		background: #0066cc;
		color: white;
	}

	.step.complete .step-number {
		background: #16a34a;
		color: white;
	}

	.form-section {
		display: flex;
		flex-direction: column;
		gap: 16px;
		margin-bottom: 24px;
	}

	input,
	select {
		padding: 12px;
		border: 1px solid #ccc;
		border-radius: 4px;
		font-size: 16px;
	}

	.actions {
		display: flex;
		gap: 12px;
		justify-content: space-between;
	}

	button {
		padding: 12px 24px;
		background: #0066cc;
		color: white;
		border: none;
		border-radius: 4px;
		cursor: pointer;
		font-size: 16px;
	}

	button:disabled {
		background: #ccc;
		cursor: not-allowed;
	}

	button[type='button'] {
		background: #666;
	}
</style>

Como funciona passo a passo:

Um único objeto formData armazena todos os campos em todas as etapas
currentStep controla a visibilidade via condicionais
Cada etapa tem um validador $derived apenas para os campos relevantes
"Próximo" desativado até que a etapa atual seja válida; "Voltar" sempre habilitado
Classes CSS mostram o estado visual ativo/completo/pendente
O botão de envio apenas na etapa final garante que toda validação foi aprovada

Técnicas-chave: Fonte única de verdade para dados do formulário, validação granular por etapa, divulgação progressiva via {#if}, classes CSS reativas, estados de botão condicionais.

Boas práticas de UX: Sempre permitir navegação para trás, validação rigorosa para avançar, rastreamento claro de progresso, persistência de dados entre etapas, erros de campo embutidos.

Acessibilidade: Landmarks ARIA progressbar, navegação por teclado, anúncios para leitores de tela via aria-live, gerenciamento de foco nas mudanças de etapa, resumo de erros para leitores de tela.

Aprimoramentos para produção: Salvamento automático no localStorage, roteamento baseado em URL para etapas, validação de campo ao vivo (com debounce), pulo de etapas para usuários avançados, exibição de percentual de progresso, aviso de beforeunload.

Variações: Navegação não linear, etapas condicionais com base nas respostas, etapa de revisão antes do envio, salvar e retomar com URLs únicas, lógica de ramificação para diferentes caminhos.

4. Construtor de Formulários Dinâmico com Gerenciamento Flexível de Campos

O Problema: As aplicações precisam de formulários onde os usuários possam adicionar/remover campos dinamicamente, configurar propriedades e reordenar elementos. Formulários estáticos não conseguem lidar com construtores de pesquisa, cadastro personalizado ou coleta de dados configurada por administradores.

A Solução: Sistema meta-form separando a configuração de campos dos dados do formulário. Os usuários adicionam/removem/configuram campos dinamicamente enquanto todos os valores permanecem vinculados e reativos.

<script>
	let fields = $state([
		{ id: 1, type: 'text', label: 'Name', value: '', required: true },
		{ id: 2, type: 'email', label: 'Email', value: '', required: true }
	])

	let nextId = $state(3)

	function addField(type) {
		fields = [
			...fields,
			{
				id: nextId++,
				type,
				label: `New ${type} field`,
				value: type === 'checkbox' ? false : '',
				required: false
			}
		]
	}

	function removeField(id) {
		fields = fields.filter((f) => f.id !== id)
	}

	function updateField(id, updates) {
		fields = fields.map((f) => (f.id === id ? { ...f, ...updates } : f))
	}

	let formValues = $derived(
		fields.reduce((acc, field) => {
			acc[field.label] = field.value
			return acc
		}, {})
	)

	let isValid = $derived(
		fields.every((field) => !field.required || (field.value && field.value !== ''))
	)
</script>

<div class="form-builder">
	<h2>Form Builder</h2>

	<div class="toolbar">
		<button onclick={() => addField('text')}>+ Text</button>
		<button onclick={() => addField('email')}>+ Email</button>
		<button onclick={() => addField('number')}>+ Number</button>
		<button onclick={() => addField('checkbox')}>+ Checkbox</button>
		<button onclick={() => addField('textarea')}>+ Text Area</button>
	</div>

	<form>
		{#each fields as field (field.id)}
			<div class="field-row">
				<input
					type="text"
					value={field.label}
					oninput={(e) => updateField(field.id, { label: e.target.value })}
					placeholder="Label"
				/>

				<label>
					<input
						type="checkbox"
						checked={field.required}
						onchange={(e) => updateField(field.id, { required: e.target.checked })}
					/>
					Required
				</label>

				{#if field.type === 'checkbox'}
					<label>
						<input type="checkbox" bind:checked={field.value} />
						{field.label}
					</label>
				{:else if field.type === 'textarea'}
					<textarea bind:value={field.value} placeholder={field.label}></textarea>
				{:else}
					<input type={field.type} bind:value={field.value} placeholder={field.label} />
				{/if}

				<button onclick={() => removeField(field.id)}>×</button>
			</div>
		{/each}
	</form>

	<div class="output">
		<h3>Form Data:</h3>
		<pre>{JSON.stringify(formValues, null, 2)}</pre>
		<p>Valid: {isValid ? '✓' : '✗'}</p>
	</div>
</div>

<style>
	.field-row {
		display: flex;
		gap: 8px;
		margin-bottom: 12px;
		padding: 12px;
		background: #f9f9f9;
		border-radius: 4px;
	}
	button {
		padding: 8px 12px;
		cursor: pointer;
	}
</style>

Como funciona: Metadados de campos em array, adição/remoção dinâmica via operações de array, rótulos editáveis, renderização específica por tipo, valores vinculados, payload de envio derivado.

Técnicas-chave: Array de campos heterogêneos, vinculação a itens do array, $derived para transformação, #each com chave usando IDs, renderização condicional por tipo.

Casos de uso: Construtores de pesquisa, personalização de CRM, cadastro para eventos, ferramentas de coleta de dados, configuração de formulários por administradores.

Aprimoramentos para produção: Modelos de campos, arrastar e soltar, lógica condicional, validação avançada, agrupamento de campos, salvar como modelo, colaboração em tempo real.

Considerações de Desempenho

Embora as vinculações do Svelte sejam altamente otimizadas, entender suas características de desempenho ajuda a construir aplicações mais rápidas. O insight principal: vinculações são apenas açúcar sintático sobre ouvintes de eventos e atribuições reativas. Quando usadas com sabedoria, são extremamente eficientes. Quando mal utilizadas com computações complexas ou listas grandes, podem se tornar gargalos.

Esta seção aborda armadilhas comuns de desempenho e suas soluções, ajudando você a escrever vinculações que escalam desde protótipos até produção.

1. Debouncing de Operações Custosas

O Problema: Cada caractere digitado em uma entrada vinculada dispara um evento input, que atualiza seu estado, que aciona quaisquer expressões $derived que dependem dele. Se essa computação derivada for custosa (filtrar milhares de itens, cálculos complexos, chamadas de API), você estará realizando trabalho pesado a cada tecla pressionada.

Cenário de exemplo: Um usuário digita "svelte" em uma caixa de pesquisa. São 6 teclas pressionadas, disparando 6 filtragens completas da lista, 6 operações de regex, 6 atualizações do DOM. Se sua lista tiver 10.000 itens, você acabou de realizar 60.000 operações de filtragem desnecessariamente.

A Solução: Aplicar debounce em operações custosas para aguardar até que o usuário pare de digitar antes de realizar o trabalho pesado.

<!-- AVOID: Expensive operation on every keystroke -->
<script>
	let searchTerm = $state('')
	let products = $state([/* 10,000 products */])

	// This runs on EVERY keystroke - very expensive!
	let filtered = $derived(
		products.filter(product => {
			// Complex filtering logic
			const matchesName = product.name.toLowerCase().includes(searchTerm.toLowerCase())
			const matchesTags = product.tags.some(tag => tag.includes(searchTerm))
			const matchesDescription = product.description.toLowerCase().includes(searchTerm.toLowerCase())
			return matchesName || matchesTags || matchesDescription
		})
	)
</script>

<input bind:value={searchTerm} placeholder="Search products..." />
<p>{filtered.length} results</p>

<!-- PREFERRED: Debounce the expensive computation -->
<script>
	let searchTerm = $state('') // Updates instantly for UI feedback
	let debouncedSearch = $state('') // Updates after user stops typing
	let debounceTimer

	// Debounce the search term
	$effect(() => {
		clearTimeout(debounceTimer)
		debounceTimer = setTimeout(() => {
			debouncedSearch = searchTerm
		}, 300) // Wait 300ms after last keystroke

		// Cleanup function prevents memory leaks
		return () => clearTimeout(debounceTimer)
	})

	// Expensive operation only runs when debouncedSearch changes
	let filtered = $derived(
		products.filter(product => {
			const matchesName = product.name.toLowerCase().includes(debouncedSearch.toLowerCase())
			const matchesTags = product.tags.some(tag => tag.includes(debouncedSearch))
			const matchesDescription = product.description.toLowerCase().includes(debouncedSearch.toLowerCase())
			return matchesName || matchesTags || matchesDescription
		})
	)
</script>

<input bind:value={searchTerm} placeholder="Search products..." />
<p>{filtered.length} results</p>

Por que isso funciona:

searchTerm é atualizado imediatamente → o usuário vê o que está digitando sem atraso
debouncedSearch é atualizado 300ms após o fim da digitação → o trabalho custoso é executado uma vez, não 6 vezes
A função de limpeza garante que os timers sejam devidamente encerrados ao desmontar o componente

Impacto no desempenho: Para uma lista de 10.000 itens com uma busca de 6 caracteres, isso reduz as operações de 60.000 para 10.000 — uma melhoria de 6x. Os usuários não percebem o atraso de 300ms porque ainda estão digitando.

Ajustando o atraso do debounce:

100-200ms: Bom para digitadores rápidos, parece muito responsivo
300-400ms: Padrão, funciona para a maioria dos casos de uso
500ms+: Parece lento, use apenas para operações muito custosas

Alternativa: Throttling

Enquanto o debouncing aguarda o fim da digitação, o throttling limita as atualizações a uma frequência máxima:

<script>
	let searchTerm = $state('')
	let debouncedSearch = $state('')
	let lastUpdate = 0

	$effect(() => {
		const now = Date.now()
		if (now - lastUpdate > 300) {
			debouncedSearch = searchTerm
			lastUpdate = now
		}
	})
</script>

O throttling fornece atualizações periódicas durante a digitação, o que pode parecer mais responsivo para busca ao vivo.

2. Evitando Vinculações em Listas Grandes

O Problema: Quando você vincula a propriedades dentro de um loop #each com centenas ou milhares de itens, o Svelte cria esse número de vinculações bidirecionais. Cada vinculação adiciona um ouvinte de evento e, quando os itens são atualizados, todos esses ouvintes disparam. Isso pode causar problemas de desempenho durante atualizações rápidas.

Cenário de exemplo: Uma lista de tarefas com 1.000 itens, cada um com uma caixa de seleção. Clicar em "Selecionar Todos" dispara 1.000 atualizações de vinculação individuais, cada uma potencialmente acionando reatividade separadamente.

<!-- AVOID: Bindings in large lists can be slow -->
<script>
	let todos = $state(Array.from({ length: 1000 }, (_, i) => ({
		id: i,
		text: `Todo ${i}`,
		completed: false
	})))

	function toggleAll() {
		const allCompleted = todos.every(todo => todo.completed)
		todos = todos.map(todo => ({ ...todo, completed: !allCompleted }))
	}
</script>

<!-- This creates 1,000 two-way bindings -->
{#each todos as todo (todo.id)}
	<label>
		<input type="checkbox" bind:checked={todo.completed} />
		{todo.text}
	</label>
{/each}

<!-- PREFERRED: Use event handlers for batch updates -->
<script>
	let todos = $state(Array.from({ length: 1000 }, (_, i) => ({
		id: i,
		text: `Todo ${i}`,
		completed: false
	})))

	function toggleTodo(id, completed) {
		// Create new array to trigger reactivity
		todos = todos.map(todo =>
			todo.id === id ? { ...todo, completed } : todo
		)
	}

	function toggleAll() {
		const allCompleted = todos.every(todo => todo.completed)
		todos = todos.map(todo => ({ ...todo, completed: !allCompleted }))
	}
</script>

{#each todos as todo (todo.id)}
	<label>
		<input
			type="checkbox"
			checked={todo.completed}
			onchange={(e) => toggleTodo(todo.id, e.target.checked)}
		/>
		{todo.text}
	</label>
{/each}

Por que isso funciona:

Sem vinculações bidirecionais significa menos ouvintes de eventos
Atualizações em lote podem ser otimizadas (atualizar vários itens em uma única passagem)
Mais fácil de adicionar registro, analytics ou validação

Quando as vinculações ainda são adequadas:

Listas com menos de ~100 itens (as vinculações são muito eficientes nessa escala)
Itens atualizados com pouca frequência (usuário marcando caixas manualmente)
Simplicidade importa mais do que micro-otimizações

Avançado: Listas Virtuais

Para listas verdadeiramente grandes (10.000+ itens), considere virtualizar:

<script>
	import VirtualList from 'svelte-virtual-list'

	let items = $state(
		Array.from({ length: 100000 }, (_, i) => ({
			id: i,
			text: `Item ${i}`,
			selected: false
		}))
	)
</script>

<!-- Only renders visible items + buffer -->
<VirtualList {items} let:item height="400px">
	<label>
		<input
			type="checkbox"
			checked={item.selected}
			onchange={(e) => {
				item.selected = e.target.checked
				items = items
			}}
		/>
		{item.text}
	</label>
</VirtualList>

3. Vinculações vs. Manipuladores de Eventos: Quando Usar Cada Um

A Troca: Vinculações são concisas e declarativas, mas manipuladores de eventos oferecem mais controle. Entender quando usar cada um melhora tanto a clareza do código quanto o desempenho.

Use bind: quando:

Sincronização simples sem transformação
O relacionamento é puramente declarativo: "esta entrada controla esta variável"
Nenhuma validação ou efeito colateral é necessário
Prototipagem rápida onde a simplicidade importa

<!-- PREFERRED: Perfect use of bind: -->
<script>
	let username = $state('')
	let age = $state(0)
	let newsletter = $state(false)
</script>

<input type="text" bind:value={username} />
<input type="number" bind:value={age} />
<input type="checkbox" bind:checked={newsletter} />

Use manipuladores de eventos quando:

Você precisa transformar ou validar a entrada
Efeitos colaterais são necessários (chamadas de API, analytics)
Atualizações condicionais (atualizar apenas se a validação passar)
Lógica de negócios complexa envolve a atualização

<!-- PREFERRED: Event handler for complex logic -->
<script>
	let username = $state('')
	let usernameError = $state('')

	function handleUsernameInput(e) {
		let value = e.target.value

		// Transform: trim and lowercase
		value = value.trim().toLowerCase()

		// Validate
		if (value.length < 3) {
			usernameError = 'Username must be at least 3 characters'
		} else if (!/^[a-z0-9_]+$/.test(value)) {
			usernameError = 'Only letters, numbers, and underscores allowed'
		} else if (value.length > 20) {
			usernameError = 'Username too long'
			return // Don't update if too long
		} else {
			usernameError = ''
		}

		// Side effect: check availability
		checkUsernameAvailability(value)

		// Only update if valid
		username = value
	}
</script>

<input type="text" value={username} oninput={handleUsernameInput} aria-invalid={!!usernameError} />
{#if usernameError}
	<p class="error">{usernameError}</p>
{/if}

Comparação de desempenho:

<!-- bind: is equivalent to this: -->
<input
	value={variable}
	oninput={(e) => {
		variable = e.target.value
	}}
/>

Não há diferença de desempenho entre bind: e uma atribuição simples em um manipulador de evento. As considerações de desempenho vêm do que você faz após a atribuição (derivações custosas, chamadas de API, etc.).

4. Memoização para Valores Derivados Custosos

O Problema: Expressões $derived recalculam sempre que suas dependências mudam. Se um valor derivado depende de uma entrada vinculada E esse cálculo é custoso, você está realizando trabalho pesado a cada tecla pressionada.

<!-- AVOID: Expensive calculation on every keystroke -->
<script>
	let csvData = $state('')

	// Parses CSV on every character typed!
	let parsedData = $derived.by(() => {
		const rows = csvData.split('\n')
		return rows.map((row) => row.split(','))
	})
</script>

<textarea bind:value={csvData}></textarea>

Solução: podemos usar debouncing e memoização

<!-- PREFERRED: Debounce + memoization -->
<script>
	let csvData = $state('')
	let debouncedCsv = $state('')
	let debounceTimer

	$effect(() => {
		clearTimeout(debounceTimer)
		debounceTimer = setTimeout(() => {
			debouncedCsv = csvData
		}, 500)
		return () => clearTimeout(debounceTimer)
	})

	// Only parses when user stops typing
	let parsedData = $derived.by(() => {
		if (!debouncedCsv) return []
		const rows = debouncedCsv.split('\n')
		return rows.map((row) => row.split(','))
	})
</script>

<textarea bind:value={csvData}></textarea><p>Rows: {parsedData.length}</p>

5. Atualizações em Lote para Múltiplas Vinculações

O Problema: Quando múltiplos valores vinculados mudam simultaneamente (por exemplo, ao redefinir um formulário), cada vinculação aciona a reatividade de forma independente. Isso pode causar re-renderizações desnecessárias.

<!-- AVOID: Multiple separate updates -->
<script>
	let firstName = $state('')
	let lastName = $state('')
	let email = $state('')

	function resetForm() {
		firstName = '' // Triggers reactivity
		lastName = '' // Triggers reactivity
		email = '' // Triggers reactivity
		// 3 separate updates!
	}
</script>

Solução: Use atualização em lote

<!-- PREFERRED: Batch update with object state -->
<script>
	let formData = $state({
		firstName: '',
		lastName: '',
		email: ''
	})

	function resetForm() {
		// Single object update triggers reactivity once
		formData = { firstName: '', lastName: '', email: '' }
	}
</script>

<input bind:value={formData.firstName} />
<input bind:value={formData.lastName} />
<input bind:value={formData.email} />

Por que isso funciona: A reatividade do Svelte é inteligente o suficiente para agrupar atualizações no mesmo objeto, reduzindo a sobrecarga de re-renderização.

6. Evitando Vinculações de Dimensão Desnecessárias

O Problema: Vinculações de dimensão (clientWidth, offsetHeight, etc.) utilizam ResizeObserver, que dispara callbacks a cada mudança de tamanho. Vincular dimensões em muitos elementos pode impactar o desempenho.

<!-- PREFERRED: Bind only to the container -->
<script>
	let containerWidth = $state(0)
	let containerHeight = $state(0)
</script>

<!-- AVOID: Binding dimensions on every item -->
{#each items as item}
	<div bind:clientWidth={item.width} bind:clientHeight={item.height}>
		{item.content}
	</div>
{/each}

<div bind:clientWidth={containerWidth} bind:clientHeight={containerHeight}>
	{#each items as item}
		<div>
			{item.content}
			<!-- Calculate item size based on container -->
		</div>
	{/each}
</div>

Princípio-chave: Meça uma vez no nível do contêiner, calcule os tamanhos dos filhos com CSS ou JavaScript.

Resumo de Desempenho

FAÇA:

Aplique debounce em operações custosas acionadas por vinculações
Use manipuladores de eventos para lógica complexa em vez de vinculações
Agrupe atualizações reunindo estados relacionados em objetos
Meça o desempenho com dados reais (não otimize prematuramente)
Considere listas virtuais para 1.000+ itens

NÃO FAÇA:

Vincular a cálculos $derived custosos que executam a cada tecla pressionada
Usar vinculações em listas grandes sem medir o desempenho primeiro
Vincular dimensões em cada item de uma lista
Otimizar vinculações antes de ter um problema de desempenho

Lembre-se: As vinculações do Svelte são altamente otimizadas. A maioria dos problemas de desempenho vem de computações custosas ou renderização de listas grandes — não das vinculações em si. Perfile sua aplicação antes de otimizar.

Boas Práticas de Acessibilidade

As vinculações não tornam os formulários acessíveis automaticamente. Sempre siga estas diretrizes:

1. Use Proper Labels

Todo input deve ter um label associado:

<!-- AVOID: No label -->
<input bind:value={email} />

<!-- PREFERRED: Explicit label -->
<label for="email">Email</label>
<input id="email" type="email" bind:value={email} />

<!-- PREFERRED: Implicit label -->
<label>
	Email
	<input type="email" bind:value={email} />
</label>

2. Forneça Feedback de Erro

Use atributos ARIA para anunciar erros aos leitores de tela:

<script>
	let email = $state('')
	let touched = $state(false)
	let isValid = $derived(/\S+@\S+\.\S+/.test(email))
	let showError = $derived(touched && !isValid && email.length > 0)
</script>

<label for="email">Email</label>
<input
	id="email"
	type="email"
	bind:value={email}
	onblur={() => (touched = true)}
	aria-invalid={showError}
	aria-describedby={showError ? 'email-error' : undefined}
/>

{#if showError}
	<p id="email-error" role="alert">Please enter a valid email address</p>
{/if}

3. Use Fieldsets para Grupos

Agrupe inputs relacionados com <fieldset> e <legend>:

<fieldset>
	<legend>Shipping Method</legend>

	<label>
		<input type="radio" bind:group={shipping} value="standard" />
		Standard (5-7 days)
	</label>

	<label>
		<input type="radio" bind:group={shipping} value="express" />
		Express (2-3 days)
	</label>
</fieldset>

Resumo de Boas Práticas

Use bind: para sincronização bidirecional simples: Formulários e inputs se beneficiam da brevidade do binding
Prefira event handlers para lógica complexa: Validação, formatação e efeitos colaterais precisam de controle explícito
Marque props de componente como $bindable: Habilite o binding bidirecional pai-filho quando apropriado
Proteja-se contra undefined em inputs numéricos: Inputs numéricos vazios tornam-se undefined — trate isso explicitamente
Use bind:group para grupos de checkbox/radio: Gerencie arrays de seleções de forma limpa
Aplique debounce em operações custosas: Não recalcule a cada tecla pressionada
Sempre forneça labels: Acessibilidade não é negociável
Valide valores iniciais de select: Certifique-se de que os valores vinculados correspondam aos valores das opções
Use bind:this para acesso ao DOM: Capture referências para APIs imperativas
Combine bindings com validação: Mostre feedback claro aos usuários

Referência Rápida

<!-- Text inputs -->
<input type="text" bind:value={text} />
<textarea bind:value={text}></textarea>

<!-- Number inputs (auto-convert to number) -->
<input type="number" bind:value={number} />
<input type="range" bind:value={number} min="0" max="100" />

<!-- Single checkbox (boolean) -->
<input type="checkbox" bind:checked={boolean} />
<input type="checkbox" bind:indeterminate />

<!-- Checkbox group (array) -->
<input type="checkbox" bind:group={array} value="option1" />
<input type="checkbox" bind:group={array} value="option2" />

<!-- Radio buttons (string/number/object) -->
<input type="radio" bind:group={selected} value="a" />
<input type="radio" bind:group={selected} value="b" />

<!-- Select dropdown -->
<select bind:value={selected}>
	<option value="a">A</option>
	<option value="b" selected>B</option>
</select>

<!-- Select multiple (array) -->
<select bind:value={array} multiple>
	<option value="a">A</option>
	<option value="b">B</option>
</select>

<!-- File input -->
<input type="file" bind:files accept="image/*" multiple />

<!-- Details element -->
<details bind:open={isOpen}>
	<summary>Click to toggle</summary>
	<p>Content</p>
</details>

<!-- Contenteditable -->
<div contenteditable bind:innerHTML={html}></div>
<div contenteditable bind:innerText={text}></div>
<div contenteditable bind:textContent={text}></div>

<!-- Media (two-way) -->
<video bind:currentTime bind:playbackRate bind:paused bind:volume bind:muted></video>

<!-- Media (readonly) -->
<video
	bind:duration
	bind:buffered
	bind:seeking
	bind:ended
	bind:readyState
	bind:videoWidth
	bind:videoHeight
></video>

<!-- Image (readonly) -->
<img bind:naturalWidth bind:naturalHeight />

<!-- Dimensions (readonly) -->
<div bind:clientWidth bind:clientHeight bind:offsetWidth bind:offsetHeight bind:contentRect></div>

<!-- Element reference -->
<input bind:this={inputElement} />

<!-- Component binding -->
<Child bind:value={parentValue} />

<!-- Function binding (Svelte 5.9+) -->
<input bind:value={() => value, (v) => (value = v.toUpperCase())} />

Conclusão

A diretiva bind: representa um dos recursos mais poderosos do Svelte para construir UIs interativas: fluxo de dados bidirecional que sincroniza automaticamente o estado do DOM com o estado do componente. Ao abstrair a fiação manual de event listeners, extração de valores e atualizações de estado exigidas no JavaScript puro, bind: transforma o que seriam dezenas de linhas de código imperativo em um único atributo declarativo. De inputs de formulário simples a composições complexas de componentes, o binding bidirecional fornece a base para interfaces reativas e interativas.

Dominar o bind: requer entender suas diversas formas e casos de uso adequados. Bindings de elementos de formulário (bind:value, bind:checked) tratam a entrada do usuário. Bindings de dimensão (bind:clientWidth) habilitam layouts responsivos. Bindings de componente com $bindable() criam padrões poderosos de comunicação pai-filho. O ponto-chave é reconhecer quando o binding bidirecional simplifica seu código versus quando o fluxo de dados unidirecional com event handlers explícitos oferece uma arquitetura melhor. Ao combinar bind: com $derived para transformações computadas e $effect para efeitos colaterais em mudanças de valores vinculados, você pode construir sistemas reativos sofisticados e de fácil manutenção.

Principais Conclusões

bind: cria fluxo de dados bidirecional sincronizando automaticamente valores do DOM com o estado do componente e vice-versa, eliminando o boilerplate manual de event listeners e atualizações de estado
Bindings de elementos de formulário tratam a entrada do usuário com bind:value para inputs de texto/número, bind:checked para checkboxes, bind:group para radio buttons e bind:files para inputs de arquivo
Bindings de dimensão fornecem dados de layout responsivo - bind:clientWidth, bind:clientHeight, bind:offsetWidth, bind:offsetHeight rastreiam dimensões de elementos de forma reativa
Bindings de componente exigem props $bindable() no componente filho para optar pelo binding bidirecional: let { value = $bindable() } = $props()
bind:this captura referências de elementos para acesso programático ao DOM: let element; bind:this={element} armazena o nó DOM em uma variável
A coerção de tipos ocorre automaticamente com type="number" convertendo inputs de string para números; <input bind:value={numericState} type="number"> popula o estado com tipos numéricos
Bindings de grupo habilitam conjuntos de radio/checkbox - múltiplos elementos com bind:group={selectedValue} sincronizam com uma única variável de estado, armazenando o(s) valor(es) marcado(s)
Bindings de função transformam valores (Svelte 5.9+): bind:value={(() => getter, (v) => setter)} aplica lógica personalizada durante as operações de get/set

Veja Também

Documentação Oficial do Svelte 5 - bind:
$state - Estado reativo que os bindings atualizam
$bindable() - Tornando props de componente vinculáveis
$derived - Valores computados a partir do estado vinculado
$effect - Efeitos colaterais disparados por mudanças em valores vinculados
Validação de Formulários - Padrões de validação de formulários no lado do cliente
MDN - Tipos de Input - Entendendo os tipos do elemento input HTML

Fluxo de Dados Bidirecional Simplificado

Entendendo o Fluxo de Dados

O Padrão Padrão de Fluxo Unidirecional

O Atalho da Vinculação Bidirecional

Quando Usar Cada Abordagem

Vinculações Básicas de Entrada

Entradas de Texto: bind:value

Entradas Numéricas: Coerção de Tipo Automática

Valores Padrão e Reset de Formulário

Vinculações de Caixas de Seleção

Caixa de Seleção Única: bind:checked

Estado Indeterminado: bind:indeterminate

Grupos de Checkboxes: bind:group

Grupos de Botões de Rádio

Dropdowns de Select

Select Simples: bind:value

Select Múltiplo: bind:value com Array

Inputs de Arquivo: bind:files

Bindings de Elementos de Mídia

Bindings de Mídia Bidirecionais

Bindings de Mídia Somente Leitura

Bindings Específicos de Vídeo

Bindings de Elemento de Imagem

Elemento Details: bind:open

Ligações Contenteditable

Ligações de Dimensão (Somente Leitura)

Referências de Elementos: bind:this

Referências de Instâncias de Componentes

Abordagem Imperativa (usando bind:this):

Abordagem Declarativa (preferida no Svelte 5):

Quando usar cada abordagem?

Abordagem híbrida

Ligações de Props de Componentes com $bindable

Tornando Props Vinculáveis

Múltiplas Props Vinculáveis

Componentes de Input Personalizados

Bindings de Função (Avançado)

Problemas Comuns e Soluções

1: Binding com Valores Derivados

2: Inputs Numéricos Tornando-se undefined

3: Binding com Propriedades de Array/Objeto

4: Binding Sem $bindable

5: Grupo de Checkboxes vs. Booleanos Individuais

6: Select Não Exibindo o Valor Inicial

Padrões do Mundo Real

1. Input de Busca com Debounce

2. Painel de Configurações com Sincronização via localStorage

3. Formulário de Múltiplas Etapas com Validação

4. Construtor de Formulários Dinâmico com Gerenciamento Flexível de Campos

Considerações de Desempenho

1. Debouncing de Operações Custosas

2. Evitando Vinculações em Listas Grandes

3. Vinculações vs. Manipuladores de Eventos: Quando Usar Cada Um

4. Memoização para Valores Derivados Custosos

5. Atualizações em Lote para Múltiplas Vinculações

6. Evitando Vinculações de Dimensão Desnecessárias

Resumo de Desempenho

Boas Práticas de Acessibilidade

1. Use Proper Labels

2. Forneça Feedback de Erro

3. Use Fieldsets para Grupos

Resumo de Boas Práticas

Referência Rápida

Conclusão

Principais Conclusões

Veja Também

Entradas de Texto: `bind:value`

Caixa de Seleção Única: `bind:checked`

Estado Indeterminado: `bind:indeterminate`

Grupos de Checkboxes: `bind:group`

Select Simples: `bind:value`

Select Múltiplo: `bind:value` com Array

Inputs de Arquivo: `bind:files`

Elemento Details: `bind:open`

Abordagem Imperativa (usando `bind:this`):

Ligações de Props de Componentes com `$bindable`

2: Inputs Numéricos Tornando-se `undefined`

4: Binding Sem `$bindable`