Fluxo de Dados Bidirecional Entre Componentes

No mundo dos frameworks baseados em componentes, os dados normalmente fluem em uma única direção: do pai para o filho. Esse fluxo de dados unidirecional torna as aplicações previsíveis e mais fáceis de depurar—você sempre sabe onde o estado vive e como ele muda. O Svelte adota essa filosofia por padrão, mas reconhece que certos padrões se beneficiam genuinamente da comunicação bidirecional.

A rune $bindable no Svelte 5 fornece uma saída controlada do fluxo de dados unidirecional, permitindo que props sejam vinculadas para que mudanças no componente filho possam fluir de volta ao pai. Este não é um padrão para se usar casualmente—o uso excessivo leva a um fluxo de dados imprevisível e componentes difíceis de manter. Mas quando usado com moderação e intencionalidade, $bindable pode simplificar dramaticamente código que de outra forma exigiria props de callback verbosas.

Este tutorial explora o $bindable de forma abrangente: desde a mecânica fundamental até padrões avançados, de armadilhas comuns a casos de uso do mundo real. Ao final, você entenderá não apenas como usar esta rune, mas quando ela é a ferramenta certa para o trabalho.

O Problema: Comunicação do Filho para o Pai

Considere construir um componente de entrada de formulário reutilizável. O pai precisa conhecer o valor atual, e o filho gerencia o elemento de input propriamente dito. Sem vinculação bidirecional, você escreveria:

<!-- TextInput.svelte -->
<script>
	let { value, onValueChange } = $props()
</script>

<input type="text" {value} oninput={(e) => onValueChange(e.target.value)} />

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

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

<TextInput value={username} onValueChange={(v) => (username = v)} /><p>Username: {username}</p>

Isso funciona, mas é verboso. Você está declarando duas props (value e onValueChange), e o pai precisa conectar um callback apenas para manter o estado sincronizado. Para um único input, isso é gerenciável. Para um formulário complexo com dezenas de campos, o código boilerplate se multiplica rapidamente.

A rune $bindable oferece uma alternativa mais limpa:

<!-- TextInput.svelte -->
<script>
	let { value = $bindable() } = $props()
</script>

<input type="text" bind:value />

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

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

<TextInput bind:value={username} /><p>Username: {username}</p>

O pai usa bind:value para estabelecer uma conexão bidirecional. Mudanças no input em TextInput atualizam automaticamente username em App. O código do componente filho é mais simples, e a intenção do pai é mais clara.

Sintaxe Básica e Mecânica

A rune $bindable marca uma prop como capaz de vinculação bidirecional. Ela é usada dentro da desestruturação de $props():

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

Características Principais

Vinculação opcional: Marcar uma prop como $bindable significa que ela pode ser vinculada, não que ela deve ser. Os pais ainda podem passar props regulares (não vinculadas).
Valores de fallback: Você pode fornecer um valor padrão que se aplica quando nenhuma prop é passada:

<script>
	let { value = $bindable('default text') } = $props()
</script>

Mutação permitida: Ao contrário das props regulares, props bindable podem ser mutadas dentro do componente filho, e essas mutações fluem de volta ao pai.

A Escolha do Pai

O componente pai decide se deve vincular:

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

	let boundValue = $state('I am bound')
	let unboundValue = 'I am not bound'
</script>

<!-- Two-way binding: changes flow both directions -->
<TextInput bind:value={boundValue} />

<!-- One-way prop: changes in TextInput don't affect unboundValue -->
<TextInput value={unboundValue} />

<!-- No prop at all: uses the fallback value -->
<TextInput />

Essa flexibilidade é crucial—o mesmo componente pode ser usado tanto em cenários controlados (vinculados) quanto não controlados (somente prop).

Como `$bindable` Difere das Props Regulares

Entender a distinção entre props regulares e props bindable é essencial para usá-las corretamente.

Props Regulares: Somente Leitura por Convenção

Com props regulares, você pode tecnicamente reatribuí-las dentro do componente filho, mas isso cria uma substituição local temporária que não afeta o pai:

<!-- Counter.svelte -->
<script>
	let { count } = $props()
</script>

<button onclick={() => count++}>
	Count: {count}
</button>

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

	let parentCount = $state(0)
</script>

<Counter count={parentCount} />
<p>Parent sees: {parentCount}</p>

<button onclick={() => parentCount++}>Increment from parent</button>

Clicar no botão do filho incrementa o count local, mas parentCount permanece inalterado. Quando o pai atualiza parentCount, a substituição local do filho é perdida. Esse comportamento é intencional—ele evita fluxo de dados inesperado enquanto permite estado local temporário.

Props Bindable: Verdadeira Comunicação Bidirecional

Com $bindable, mutações no filho refletem imediatamente no pai:

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

<button onclick={() => count++}>
	Count: {count}
</button>

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

	let parentCount = $state(0)
</script>

<Counter bind:count={parentCount} />
<p>Parent sees: {parentCount}</p>

<button onclick={() => parentCount++}>Increment from parent</button>

Agora ambos os botões afetam o mesmo valor. O incremento do filho atualiza parentCount, e o incremento do pai atualiza a exibição do filho. Sincronização bidirecional verdadeira.

Valores de Fallback: As Sutilezas

Valores de fallback em $bindable têm um comportamento específico que difere dos padrões de props regulares:

Quando os Fallbacks se Aplicam

O valor de fallback é usado somente quando:

Nenhuma prop é passada
A prop é passada como undefined

<!-- Toggle.svelte -->
<script>
	let { checked = $bindable(false) } = $props()
</script>

<input type="checkbox" bind:checked />
<span>{checked ? 'On' : 'Off'}</span>

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

	let explicitValue = $state(true)
	let undefinedValue = $state(undefined)
</script>

<!-- Uses explicitValue (true) -->
<Toggle bind:checked={explicitValue} />

<!-- Uses fallback (false) because value is undefined -->
<Toggle bind:checked={undefinedValue} />

<!-- Uses fallback (false) because no prop passed -->
<Toggle />

Props Vinculadas Devem Ter Valores

Quando uma prop é vinculada (usando bind:), espera-se que o pai forneça um valor definido. Se uma prop vinculada recebe undefined enquanto tem um fallback, o Svelte lança um erro em tempo de execução:

<!-- This will throw an error! -->
<script>
	import Toggle from './Toggle.svelte'

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

<Toggle bind:checked={value} />
<!-- Runtime error: bound prop 'checked' is undefined -->

Essa rigidez evita situações ambíguas onde não está claro se o fallback ou o valor do pai deve ser aplicado.

Props Vinculadas Devem Ter Valores

Quando você usa bind: em uma prop, o Svelte exige que o valor do pai seja definido. Se o pai fornece undefined para uma prop vinculada que tem um fallback, o Svelte lança um erro em tempo de execução. Sempre inicialize seu estado antes de vincular: let value = $state('').

Props Não Vinculadas Podem Ser Undefined

Para props não vinculadas, undefined simplesmente aciona o fallback:

<!-- This works fine -->
<Toggle checked={undefined} />
<!-- Uses fallback value (false) -->

Vinculação a Propriedades de Objetos e Proxies de Estado

Ao trabalhar com objetos, $bindable interage com o sistema de reatividade do Svelte de maneiras importantes.

Vinculando Propriedades de Objetos

Você pode vincular a propriedades de objetos reativos:

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

	let form = $state({
		username: '',
		email: '',
		password: ''
	})
</script>

<TextInput bind:value={form.username} placeholder="Username" />
<TextInput bind:value={form.email} placeholder="Email" />
<TextInput bind:value={form.password} placeholder="Password" type="password" />

<pre>{JSON.stringify(form, null, 2)}</pre>

Cada input vincula a uma propriedade específica do objeto form. Mudanças em qualquer input atualizam a propriedade correspondente de forma reativa.

Mutações de State Proxy

Quando um proxy $state é passado como prop (vinculado ou não), mutações nesse proxy no filho afetarão o pai. No entanto, há uma distinção crucial:

Sem $bindable: Mutar um prop de state proxy aciona um aviso porque o filho está modificando um estado que não "pertence" a ele:

<!-- Child.svelte -->
<script>
	let { user } = $props() // Not bindable
</script>

<button onclick={() => (user.name = 'Changed')}> Change name </button>
<!-- Works but shows ownership_invalid_mutation warning -->

Com $bindable: O filho reconhece explicitamente que pode modificar o prop:

<!-- Child.svelte -->
<script>
	let { user = $bindable() } = $props()
</script>

<button onclick={() => (user.name = 'Changed')}> Change name </button>
<!-- No warning - mutation is expected -->

Quando Vincular Objetos vs. Primitivos

Considere se você precisa vincular o objeto inteiro ou propriedades específicas:

<!-- Binding specific properties (preferred for forms) -->
<UserForm bind:name={user.name} bind:email={user.email} />

<!-- Binding the entire object (useful for complex state) -->
<UserEditor bind:user />

Vincular propriedades específicas é mais explícito e facilita o rastreamento do fluxo de dados. Vincular objetos inteiros é apropriado quando o filho gerencia legitimamente o estado completo do objeto.

Casos de Uso do Mundo Real

1. Componentes de Input de Formulário

O caso de uso mais comum — criar wrappers de input reutilizáveis:

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

	let inputId = $props.id()
</script>

<div class="form-field" class:has-error={error}>
	<label for={inputId}>
		{label}
		{#if required}<span class="required">*</span>{/if}
	</label>

	<input
		id={inputId}
		{type}
		bind:value
		class:invalid={error}
		aria-describedby={error ? `${inputId}-error` : undefined}
	/>

	{#if error}
		<span id="{inputId}-error" class="error-message">{error}</span>
	{/if}
</div>

<style>
	.form-field {
		display: flex;
		flex-direction: column;
		gap: 0.25rem;
		margin-bottom: 1rem;
	}

	.required {
		color: #dc2626;
	}

	.invalid {
		border-color: #dc2626;
	}

	.error-message {
		color: #dc2626;
		font-size: 0.875rem;
	}
</style>

<!-- RegistrationForm.svelte -->
<script>
	import FormField from './FormField.svelte'

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

	let errors = $state({})

	function validate() {
		errors = {}

		if (formData.username.length < 3) {
			errors.username = 'Username must be at least 3 characters'
		}

		if (!formData.email.includes('@')) {
			errors.email = 'Please enter a valid email'
		}

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

		return Object.keys(errors).length === 0
	}

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

<form
	onsubmit={(e) => {
		e.preventDefault()
		handleSubmit(e)
	}}
>
	<FormField label="Username" bind:value={formData.username} error={errors.username} required />

	<FormField label="Email" type="email" bind:value={formData.email} error={errors.email} required />

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

	<button type="submit">Register</button>
</form>

Gerenciando o estado aberto/fechado a partir do pai ou do filho:

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

	function close() {
		open = false
	}

	function handleBackdropClick(event) {
		if (event.target === event.currentTarget) {
			close()
		}
	}

	function handleKeydown(event) {
		if (event.key === 'Escape') {
			close()
		}
	}
</script>

{#if open}
	<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
	<div
		class="modal-backdrop"
		onclick={handleBackdropClick}
		onkeydown={handleKeydown}
		role="dialog"
		aria-modal="true"
		aria-labelledby="modal-title"
	>
		<div class="modal-content">
			<header>
				<h2 id="modal-title">{title}</h2>
				<button class="close-button" onclick={close} aria-label="Close"> × </button>
			</header>
			<div class="modal-body">
				{@render children?.()}
			</div>
		</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;
		z-index: 1000;
	}

	.modal-content {
		background: white;
		border-radius: 8px;
		max-width: 500px;
		width: 90%;
		max-height: 90vh;
		overflow: auto;
	}

	header {
		display: flex;
		justify-content: space-between;
		align-items: center;
		padding: 1rem;
		border-bottom: 1px solid #e5e7eb;
	}

	.close-button {
		background: none;
		border: none;
		font-size: 1.5rem;
		cursor: pointer;
		padding: 0.25rem;
	}

	.modal-body {
		padding: 1rem;
	}
</style>

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

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

<button onclick={() => (showSettings = true)}>Open Settings</button>

<Modal bind:open={showSettings} title="Settings">
	<p>Configure your preferences here.</p>
	<button onclick={() => (showSettings = false)}>Save & Close</button>
</Modal>

O modal pode ser fechado pelo pai (definindo showSettings = false), clicando no backdrop, pressionando Escape ou clicando no botão de fechar — tudo por meio do mesmo estado vinculado.

3. Painéis Accordion/Retráteis

Gerenciando qual painel está expandido:

<!-- Accordion.svelte -->
<script>
	let { items, activeIndex = $bindable(null) } = $props()

	function toggle(index) {
		activeIndex = activeIndex === index ? null : index
	}
</script>

<div class="accordion">
	{#each items as item, index (item.id)}
		{@const isActive = activeIndex === index}

		<div class="accordion-item" class:active={isActive}>
			<button class="accordion-header" onclick={() => toggle(index)} aria-expanded={isActive}>
				{item.title}
				<span class="icon">{isActive ? '−' : '+'}</span>
			</button>

			{#if isActive}
				<div class="accordion-content">
					{item.content}
				</div>
			{/if}
		</div>
	{/each}
</div>

<style>
	.accordion {
		border: 1px solid #e5e7eb;
		border-radius: 8px;
		overflow: hidden;
	}

	.accordion-item {
		border-bottom: 1px solid #e5e7eb;
	}

	.accordion-item:last-child {
		border-bottom: none;
	}

	.accordion-header {
		width: 100%;
		padding: 1rem;
		background: #f9fafb;
		border: none;
		cursor: pointer;
		display: flex;
		justify-content: space-between;
		align-items: center;
		font-size: 1rem;
		text-align: left;
	}

	.accordion-header:hover {
		background: #f3f4f6;
	}

	.accordion-content {
		padding: 1rem;
	}

	.active .accordion-header {
		background: #e5e7eb;
	}
</style>

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

	let expandedPanel = $state(0) // Start with first panel open

	const faqItems = [
		{ id: 1, title: 'What is Svelte?', content: 'Svelte is a compiler...' },
		{ id: 2, title: 'What are runes?', content: 'Runes are special symbols...' },
		{ id: 3, title: 'How does $bindable work?', content: 'The $bindable rune...' }
	]

	function expandAll() {
		// Could implement multi-select with array if needed
	}

	function collapseAll() {
		expandedPanel = null
	}
</script>

<div class="controls">
	<button onclick={collapseAll}>Collapse All</button>
	<span>Currently expanded: {expandedPanel ?? 'None'}</span>
</div>

<Accordion items={faqItems} bind:activeIndex={expandedPanel} />

4. Componentes de Paginação

Sincronizando o estado de página entre pai e filho:

<!-- Pagination.svelte -->
<script>
	let { currentPage = $bindable(1), totalPages, siblingCount = 1 } = $props()

	function getPageNumbers() {
		const pages = []
		const leftSibling = Math.max(currentPage - siblingCount, 1)
		const rightSibling = Math.min(currentPage + siblingCount, totalPages)

		const showLeftDots = leftSibling > 2
		const showRightDots = rightSibling < totalPages - 1

		if (!showLeftDots && showRightDots) {
			for (let i = 1; i <= 3 + 2 * siblingCount; i++) {
				if (i <= totalPages) pages.push(i)
			}
			pages.push('...')
			pages.push(totalPages)
		} else if (showLeftDots && !showRightDots) {
			pages.push(1)
			pages.push('...')
			for (let i = totalPages - (2 + 2 * siblingCount); i <= totalPages; i++) {
				if (i > 0) pages.push(i)
			}
		} else if (showLeftDots && showRightDots) {
			pages.push(1)
			pages.push('...')
			for (let i = leftSibling; i <= rightSibling; i++) {
				pages.push(i)
			}
			pages.push('...')
			pages.push(totalPages)
		} else {
			for (let i = 1; i <= totalPages; i++) {
				pages.push(i)
			}
		}

		return pages
	}

	let pageNumbers = $derived(getPageNumbers())

	function goToPage(page) {
		if (typeof page === 'number' && page >= 1 && page <= totalPages) {
			currentPage = page
		}
	}
</script>

<nav class="pagination" aria-label="Pagination">
	<button
		onclick={() => goToPage(currentPage - 1)}
		disabled={currentPage === 1}
		aria-label="Previous page"
	>
		←
	</button>

	{#each pageNumbers as page}
		{#if page === '...'}
			<span class="ellipsis">...</span>
		{:else}
			<button
				onclick={() => goToPage(page)}
				class:active={page === currentPage}
				aria-current={page === currentPage ? 'page' : undefined}
			>
				{page}
			</button>
		{/if}
	{/each}

	<button
		onclick={() => goToPage(currentPage + 1)}
		disabled={currentPage === totalPages}
		aria-label="Next page"
	>
		→
	</button>
</nav>

<style>
	.pagination {
		display: flex;
		gap: 0.25rem;
		align-items: center;
	}

	button {
		padding: 0.5rem 0.75rem;
		border: 1px solid #e5e7eb;
		background: white;
		cursor: pointer;
		border-radius: 4px;
	}

	button:hover:not(:disabled) {
		background: #f3f4f6;
	}

	button:disabled {
		opacity: 0.5;
		cursor: not-allowed;
	}

	button.active {
		background: #3b82f6;
		color: white;
		border-color: #3b82f6;
	}

	.ellipsis {
		padding: 0.5rem;
	}
</style>

<!-- DataTable.svelte -->
<script>
	import Pagination from './Pagination.svelte'

	let { data } = $props()

	let page = $state(1)
	let pageSize = 10

	let totalPages = $derived(Math.ceil(data.length / pageSize))
	let paginatedData = $derived(data.slice((page - 1) * pageSize, page * pageSize))

	// Reset to page 1 when data changes significantly
	$effect(() => {
		if (page > totalPages && totalPages > 0) {
			page = totalPages
		}
	})
</script>

<table>
	<thead>
		<tr>
			<th>ID</th>
			<th>Name</th>
			<th>Email</th>
		</tr>
	</thead>
	<tbody>
		{#each paginatedData as item (item.id)}
			<tr>
				<td>{item.id}</td>
				<td>{item.name}</td>
				<td>{item.email}</td>
			</tr>
		{/each}
	</tbody>
</table>

<Pagination bind:currentPage={page} {totalPages} />

<p>Showing page {page} of {totalPages}</p>

5. Componentes de Abas

Gerenciando o estado da aba ativa:

<!-- Tabs.svelte -->
<script>
	let { tabs, activeTab = $bindable(tabs[0]?.id), children } = $props()
</script>

<div class="tabs-container">
	<div class="tab-list" role="tablist">
		{#each tabs as tab (tab.id)}
			<button
				role="tab"
				aria-selected={activeTab === tab.id}
				aria-controls="panel-{tab.id}"
				class:active={activeTab === tab.id}
				onclick={() => (activeTab = tab.id)}
			>
				{tab.label}
			</button>
		{/each}
	</div>

	<div class="tab-panels">
		{@render children?.(activeTab)}
	</div>
</div>

<style>
	.tabs-container {
		border: 1px solid #e5e7eb;
		border-radius: 8px;
		overflow: hidden;
	}

	.tab-list {
		display: flex;
		background: #f9fafb;
		border-bottom: 1px solid #e5e7eb;
	}

	.tab-list button {
		padding: 0.75rem 1.5rem;
		border: none;
		background: transparent;
		cursor: pointer;
		font-size: 1rem;
		border-bottom: 2px solid transparent;
		margin-bottom: -1px;
	}

	.tab-list button:hover {
		background: #f3f4f6;
	}

	.tab-list button.active {
		border-bottom-color: #3b82f6;
		background: white;
	}

	.tab-panels {
		padding: 1rem;
	}
</style>

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

	let currentTab = $state('profile')

	const tabs = [
		{ id: 'profile', label: 'Profile' },
		{ id: 'settings', label: 'Settings' },
		{ id: 'notifications', label: 'Notifications' }
	]

	function goToSettings() {
		currentTab = 'settings'
	}
</script>

<Tabs {tabs} bind:activeTab={currentTab}>
	{#snippet children(active)}
		{#if active === 'profile'}
			<div id="panel-profile" role="tabpanel">
				<h3>Profile</h3>
				<p>Your profile information here.</p>
				<button onclick={goToSettings}>Go to Settings</button>
			</div>
		{:else if active === 'settings'}
			<div id="panel-settings" role="tabpanel">
				<h3>Settings</h3>
				<p>Configure your account settings.</p>
			</div>
		{:else if active === 'notifications'}
			<div id="panel-notifications" role="tabpanel">
				<h3>Notifications</h3>
				<p>Manage your notification preferences.</p>
			</div>
		{/if}
	{/snippet}
</Tabs>

Padrões Avançados

Múltiplos Props Bindable

Componentes podem ter múltiplos props bindable para interações complexas:

<!-- DateRangePicker.svelte -->
<script>
	let {
		startDate = $bindable(null),
		endDate = $bindable(null),
		minDate = null,
		maxDate = null
	} = $props()

	function handleStartChange(event) {
		startDate = event.target.value || null

		// Ensure end date is not before start date
		if (startDate && endDate && startDate > endDate) {
			endDate = startDate
		}
	}

	function handleEndChange(event) {
		endDate = event.target.value || null

		// Ensure start date is not after end date
		if (startDate && endDate && endDate < startDate) {
			startDate = endDate
		}
	}
</script>

<div class="date-range-picker">
	<div class="field">
		<label for="start-date">Start Date</label>
		<input
			id="start-date"
			type="date"
			value={startDate ?? ''}
			min={minDate}
			max={endDate ?? maxDate}
			onchange={handleStartChange}
		/>
	</div>

	<span class="separator">to</span>

	<div class="field">
		<label for="end-date">End Date</label>
		<input
			id="end-date"
			type="date"
			value={endDate ?? ''}
			min={startDate ?? minDate}
			max={maxDate}
			onchange={handleEndChange}
		/>
	</div>
</div>

<style>
	.date-range-picker {
		display: flex;
		align-items: end;
		gap: 1rem;
	}

	.field {
		display: flex;
		flex-direction: column;
		gap: 0.25rem;
	}

	.separator {
		padding-bottom: 0.5rem;
		color: #6b7280;
	}

	input {
		padding: 0.5rem;
		border: 1px solid #e5e7eb;
		border-radius: 4px;
	}
</style>

<!-- ReportFilter.svelte -->
<script>
	import DateRangePicker from './DateRangePicker.svelte'

	let filters = $state({
		startDate: '2025-01-01',
		endDate: '2025-01-31'
	})

	function applyFilter() {
		console.log('Filtering from', filters.startDate, 'to', filters.endDate)
	}
</script>

<DateRangePicker bind:startDate={filters.startDate} bind:endDate={filters.endDate} />

<button onclick={applyFilter}>Apply Filter</button>

Valores Bindable Computados: Input de Moeda

Um padrão comum é transformar valores à medida que eles fluem para dentro e para fora. Este input de moeda armazena centavos internamente (evitando problemas de ponto flutuante), mas exibe dólares formatados:

<!-- CurrencyInput.svelte -->
<script>
	let {
		// Bind cents (integer) to avoid floating-point precision issues
		cents = $bindable(0),
		currency = 'USD',
		locale = 'en-US'
	} = $props()

	let inputRef = $state(null)
	let isFocused = $state(false)

	// Format for display when not focused
	let displayValue = $derived(
		new Intl.NumberFormat(locale, {
			style: 'currency',
			currency
		}).format(cents / 100)
	)

	// Raw numeric value for editing
	let editValue = $derived((cents / 100).toFixed(2))

	function handleInput(event) {
		const raw = event.target.value.replace(/[^0-9.]/g, '')
		const dollars = parseFloat(raw) || 0
		cents = Math.round(dollars * 100)
	}

	function handleFocus() {
		isFocused = true
		// Select all text for easy replacement
		setTimeout(() => inputRef?.select(), 0)
	}

	function handleBlur() {
		isFocused = false
	}
</script>

<div class="currency-input">
	<input
		bind:this={inputRef}
		type="text"
		inputmode="decimal"
		value={isFocused ? editValue : displayValue}
		oninput={handleInput}
		onfocus={handleFocus}
		onblur={handleBlur}
	/>
</div>

<style>
	.currency-input input {
		padding: 0.5rem;
		font-size: 1rem;
		text-align: right;
		border: 1px solid #e5e7eb;
		border-radius: 4px;
		width: 150px;
	}

	.currency-input input:focus {
		outline: 2px solid #3b82f6;
		outline-offset: -1px;
	}
</style>

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

	// Store price in cents for precision
	let priceInCents = $state(1999) // $19.99
</script>

<CurrencyInput bind:cents={priceInCents} />
<p>Stored value: {priceInCents} cents (${(priceInCents / 100).toFixed(2)})</p>

O pai trabalha com centavos (inteiros), enquanto os usuários veem e editam moeda formatada. Esse padrão evita problemas de precisão de ponto flutuante comuns em aplicações financeiras.

Valores Bindable Computados: Gerador de Slug

Outro padrão prático de transformação — gerando automaticamente slugs de URL a partir de títulos, mas permitindo substituição manual:

<!-- SlugInput.svelte -->
<script>
	let { title = $bindable(''), slug = $bindable('') } = $props()

	let manuallyEdited = $state(false)

	function generateSlug(text) {
		return text
			.toLowerCase()
			.trim()
			.replace(/[^a-z0-9\s-]/g, '')
			.replace(/\s+/g, '-')
			.replace(/-+/g, '-')
			.replace(/^-|-$/g, '')
	}

	// Auto-generate slug from title unless manually edited
	$effect(() => {
		if (!manuallyEdited && title) {
			slug = generateSlug(title)
		}
	})

	function handleSlugInput(event) {
		manuallyEdited = true
		slug = generateSlug(event.target.value)
	}

	function resetToAuto() {
		manuallyEdited = false
		slug = generateSlug(title)
	}
</script>

<div class="slug-input">
	<div class="field">
		<label for="title">Title</label>
		<input id="title" type="text" bind:value={title} placeholder="Enter post title..." />
	</div>

	<div class="field">
		<label for="slug">
			Slug
			{#if manuallyEdited}
				<button type="button" class="reset-btn" onclick={resetToAuto}> ↺ Auto </button>
			{/if}
		</label>
		<div class="slug-preview">
			<span class="prefix">/blog/</span>
			<input id="slug" type="text" value={slug} oninput={handleSlugInput} placeholder="url-slug" />
		</div>
	</div>
</div>

<style>
	.slug-input {
		display: flex;
		flex-direction: column;
		gap: 1rem;
	}

	.field {
		display: flex;
		flex-direction: column;
		gap: 0.25rem;
	}

	label {
		font-weight: 500;
		display: flex;
		align-items: center;
		gap: 0.5rem;
	}

	.reset-btn {
		font-size: 0.75rem;
		padding: 0.125rem 0.375rem;
		background: #e5e7eb;
		border: none;
		border-radius: 4px;
		cursor: pointer;
	}

	.slug-preview {
		display: flex;
		align-items: center;
		border: 1px solid #e5e7eb;
		border-radius: 4px;
		overflow: hidden;
	}

	.prefix {
		padding: 0.5rem;
		background: #f3f4f6;
		color: #6b7280;
		font-family: monospace;
	}

	.slug-preview input {
		border: none;
		padding: 0.5rem;
		flex: 1;
		font-family: monospace;
	}

	.slug-preview input:focus {
		outline: none;
	}

	input {
		padding: 0.5rem;
		border: 1px solid #e5e7eb;
		border-radius: 4px;
	}
</style>

<!-- PostEditor.svelte -->
<script>
	import SlugInput from './SlugInput.svelte'

	let post = $state({
		title: '',
		slug: '',
		content: ''
	})
</script>

<SlugInput bind:title={post.title} bind:slug={post.slug} />
<p>Final URL: /blog/{post.slug || '...'}</p>

Esse padrão é essencial para construtores de CMS e blogs — o slug é gerado automaticamente a partir do título, mas pode ser personalizado manualmente quando necessário.

Bindable com Validação

Combine vinculação com validação para inputs controlados:

<!-- ValidatedInput.svelte -->
<script>
	let { value = $bindable(''), validate = () => null, transform = (v) => v } = $props()

	let error = $state(null)
	let touched = $state(false)

	function handleInput(event) {
		const rawValue = event.target.value
		const transformedValue = transform(rawValue)

		// Update the bound value
		value = transformedValue

		// Validate if touched
		if (touched) {
			error = validate(transformedValue)
		}
	}

	function handleBlur() {
		touched = true
		error = validate(value)
	}
</script>

<div class="validated-input" class:has-error={error && touched}>
	<input
		type="text"
		{value}
		oninput={handleInput}
		onblur={handleBlur}
		aria-invalid={error && touched}
	/>

	{#if error && touched}
		<span class="error">{error}</span>
	{/if}
</div>

<style>
	.validated-input {
		display: flex;
		flex-direction: column;
		gap: 0.25rem;
	}

	input {
		padding: 0.5rem;
		border: 1px solid #e5e7eb;
		border-radius: 4px;
	}

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

	.error {
		color: #dc2626;
		font-size: 0.875rem;
	}
</style>

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

	let email = $state('')

	function validateEmail(value) {
		if (!value) return 'Email is required'
		if (!value.includes('@')) return 'Please enter a valid email'
		return null
	}

	function toLowerCase(value) {
		return value.toLowerCase()
	}
</script>

<ValidatedInput bind:value={email} validate={validateEmail} transform={toLowerCase} />

<p>Email: {email}</p>

Integração com TypeScript

Tipagem correta dos props bindable garante segurança de tipos entre os limites dos componentes:

<!-- TypedInput.svelte -->
<script lang="ts">
	interface Props {
		value: string
		placeholder?: string
		disabled?: boolean
	}

	let { value = $bindable(''), placeholder = '', disabled = false }: Props = $props()
</script>

<input type="text" bind:value {placeholder} {disabled} />

Para tipos complexos:

<!-- UserEditor.svelte -->
<script lang="ts">
	interface User {
		id: number
		name: string
		email: string
		role: 'admin' | 'user' | 'guest'
	}

	interface Props {
		user: User
		onSave?: (user: User) => void
	}

	let { user = $bindable(), onSave }: Props = $props()

	function handleSave() {
		onSave?.(user)
	}
</script>

<form onsubmit|preventDefault={handleSave}>
	<input bind:value={user.name} placeholder="Name" />
	<input bind:value={user.email} type="email" placeholder="Email" />
	<select bind:value={user.role}>
		<option value="admin">Admin</option>
		<option value="user">User</option>
		<option value="guest">Guest</option>
	</select>
	<button type="submit">Save</button>
</form>

Armadilhas Comuns e Soluções

1: Esquecer `$bindable` no Filho

<!-- WRONG: Missing $bindable -->
<script>
	let { value } = $props()
</script>

<input bind:value />

<!-- Parent tries to bind -->
<Child bind:value={parentValue} />
<!-- Works but changes don't flow back up! -->

<!-- CORRECT: Use $bindable -->
<script>
	let { value = $bindable() } = $props()
</script>

<input bind:value />

2: Vinculando Valores Indefinidos

<!-- WRONG: Binding to potentially undefined -->
<script>
	let maybeValue = $state(undefined)
</script>

<Child bind:value={maybeValue} />
<!-- Runtime error if Child has a fallback! -->

<!-- CORRECT: Initialize with a valid value -->
<script>
	let value = $state('')
</script>

<Child bind:value />

3: Uso Excessivo de Bindings

Quando um componente tem muitos props vinculados, fica difícil rastrear a origem das mudanças de estado. Como orientação geral: vincule no máximo um ou dois valores por componente. Se você se pegar vinculando mais do que isso, considere se um único prop de callback estruturado não seria mais claro.

<!-- ANTIPATTERN: Everything is bound -->
<ComplexForm
	bind:firstName={form.firstName}
	bind:lastName={form.lastName}
	bind:email={form.email}
	bind:phone={form.phone}
	bind:address={form.address}
	bind:city={form.city}
	bind:country={form.country}
	bind:errors
	bind:isValid
	bind:isDirty
	bind:isSubmitting
/>

Quando muitas coisas são vinculadas, o fluxo de dados se torna imprevisível. Considere:

<!-- BETTER: Minimal binding with callbacks for actions -->
<ComplexForm
	{initialValues}
	onchange={(values) => (form = values)}
	onsubmit={handleSubmit}
	onerror={handleError}
/>

4: Mutando Props Não Vinculáveis

<!-- WRONG: Mutating a prop that isn't bindable -->
<script>
	let { items } = $props() // Not $bindable
</script>

<button onclick={() => items.push({ id: Date.now() })}> Add Item </button>
<!-- Causes ownership warning, confusing behavior -->

<!-- CORRECT: Use callback or make bindable -->
<script>
	let { items, onAddItem } = $props()
</script>

<button onclick={() => onAddItem({ id: Date.now() })}>
	Add Item
</button>

<!-- OR make it bindable if appropriate -->
<script>
	let { items = $bindable([]) } = $props()
</script>

5: Atualizações Circulares

Se um $effect lê e depois escreve um prop $bindable, ele vai se acionar novamente na próxima atualização. Proteja-se disso comparando o novo valor com o atual antes de escrever, ou reestruture a lógica para que ela pertença a um prop de callback.

<!-- DANGEROUS: Can cause infinite loops -->
<script>
	let { value = $bindable(0) } = $props()

	$effect(() => {
		// This runs when value changes
		value = value + 1 // Causes another change!
	})
</script>

<!-- CORRECT: Guard against circular updates -->
<script>
	let { value = $bindable(0) } = $props()
	let previousValue = value

	$effect(() => {
		if (value !== previousValue) {
			// Process change
			previousValue = value
		}
	})
</script>

Quando Usar `$bindable` vs. Props de Callback

Use `$bindable` Quando:

O prop representa estado de UI que tanto o pai quanto o filho precisam ler e escrever (aberto/fechado, valor selecionado, página atual)
O vínculo é intuitivo e corresponde ao funcionamento de elementos nativos (<input bind:value>)
O relacionamento é simples — um valor, sincronização bidirecional
Você está criando componentes de formulário que envolvem inputs nativos

Use Props de Callback Quando:

A ação tem efeitos colaterais além de atualizar o estado (chamadas de API, analytics, validação)
O pai precisa interceptar ou transformar a mudança antes de aplicá-la
Múltiplos valores mudam juntos e devem ser tratados atomicamente
Você precisa prevenir ou cancelar certas atualizações condicionalmente

<!-- Good use of $bindable -->
<SearchInput bind:query />
<Modal bind:open />
<Slider bind:value />
<Select bind:selected />

<!-- Better with callbacks -->
<FileUploader onupload={handleFileUpload} />
<Form onsubmit={handleSubmit} onchange={handleFormChange} />
<DataGrid onrowselect={handleRowSelect} onsort={handleSort} />

Resumo de Boas Práticas

Use $bindable com moderação — Prefira o fluxo de dados unidirecional; use binding apenas quando ele genuinamente simplificar seu código.
Sempre forneça valores de fallback para props vinculáveis opcionais, garantindo um comportamento previsível.
Documente props vinculáveis claramente — Deixe óbvio quais props suportam binding.
Valide nas fronteiras — Não assuma que valores vinculados são sempre válidos; valide tanto no pai quanto no filho quando necessário.
Prefira bindings primitivos — Vincular valores individuais é mais claro do que vincular objetos inteiros.
Considere acessibilidade — Certifique-se de que mudanças de estado de UI vinculadas sejam anunciadas para leitores de tela quando apropriado.
Teste o uso com e sem binding — Seu componente deve funcionar corretamente independentemente de o pai vincular ou não.
Evite cadeias profundas de binding — Se você se pegar vinculando através de múltiplas camadas de componentes, reconsidere sua arquitetura.

Referência Rápida

<!-- Basic bindable prop -->
<script>
	let { value = $bindable() } = $props()
</script>

<!-- With fallback value -->
<script>
	let { checked = $bindable(false) } = $props()
</script>

<!-- Multiple bindable props -->
<script>
	let {
		min = $bindable(0),
		max = $bindable(100),
		value = $bindable(50)
	} = $props()
</script>

<!-- TypeScript typed -->
<script lang="ts">
	interface Props {
		value: string
		count: number
	}

	let {
		value = $bindable(''),
		count = $bindable(0)
	}: Props = $props()
</script>

<!-- Parent usage -->
<Component bind:value={localValue} />
<Component bind:value />  <!-- shorthand when names match -->
<Component value={readOnlyValue} />  <!-- one-way, no binding -->

O rune $bindable representa a abordagem cuidadosa do Svelte à comunicação entre componentes — reconhecendo que, embora o fluxo de dados unidirecional seja o padrão ideal, o binding bidirecional controlado tem casos de uso legítimos que não deveriam exigir soluções alternativas verbosas. Use-o com critério e ele tornará as APIs dos seus componentes mais limpas e intuitivas. Use-o em excesso e você se verá depurando mudanças de estado imprevisíveis por toda a sua aplicação.

Pontos Principais

$bindable é uma saída controlada do fluxo de dados unidirecional — não é o padrão e deve ser usado com moderação apenas quando genuinamente simplificar o código.
Marcar um prop como $bindable o torna capaz de ser vinculado, não obrigatório — o pai escolhe se vincula (bind:value={x}) ou passa de forma unidirecional (value={x}); o mesmo componente funciona das duas formas.
Valores de fallback se aplicam apenas quando nenhum prop é passado ou o valor é undefined — props vinculados que recebem undefined lançam erros em tempo de execução, enquanto props não vinculados usam o fallback normalmente.
Use $bindable para estado de UI, callbacks para ações — bindable é ideal para aberto/fechado, valor selecionado, página atual; callbacks são melhores para ações com efeitos colaterais como chamadas de API ou validação.
Padrões avançados incluem transformações computadas — inputs de moeda que armazenam centavos mas exibem reais, geradores de slug que criam URLs automaticamente a partir de títulos, e validação combinando binding com tratamento de erros.
Armadilhas comuns a evitar — esquecer $bindable no filho (as mudanças não subirão), vincular valores indefinidos, usar bindings em excesso causando fluxo de dados imprevisível, e criar loops de atualização circulares com $effect.

Fluxo de Dados Bidirecional Entre Componentes

O Problema: Comunicação do Filho para o Pai

Sintaxe Básica e Mecânica

Características Principais

A Escolha do Pai

Como $bindable Difere das Props Regulares

Props Regulares: Somente Leitura por Convenção

Props Bindable: Verdadeira Comunicação Bidirecional

Valores de Fallback: As Sutilezas

Quando os Fallbacks se Aplicam

Props Vinculadas Devem Ter Valores

Props Vinculadas Devem Ter Valores

Props Não Vinculadas Podem Ser Undefined

Vinculação a Propriedades de Objetos e Proxies de Estado

Vinculando Propriedades de Objetos

Mutações de State Proxy

Quando Vincular Objetos vs. Primitivos

Casos de Uso do Mundo Real

1. Componentes de Input de Formulário

2. Componentes de Modal e Diálogo

3. Painéis Accordion/Retráteis

4. Componentes de Paginação

5. Componentes de Abas

Padrões Avançados

Múltiplos Props Bindable

Valores Bindable Computados: Input de Moeda

Valores Bindable Computados: Gerador de Slug

Bindable com Validação

Integração com TypeScript

Armadilhas Comuns e Soluções

1: Esquecer $bindable no Filho

2: Vinculando Valores Indefinidos

3: Uso Excessivo de Bindings

4: Mutando Props Não Vinculáveis

5: Atualizações Circulares

Quando Usar $bindable vs. Props de Callback

Use $bindable Quando:

Use Props de Callback Quando:

Resumo de Boas Práticas

Referência Rápida

Pontos Principais

Veja Também

Documentação Oficial

Recursos Externos

Como `$bindable` Difere das Props Regulares

1: Esquecer `$bindable` no Filho

Quando Usar `$bindable` vs. Props de Callback

Use `$bindable` Quando: