Flujo de Datos Bidireccional Entre Componentes

En el mundo de los frameworks basados en componentes, los datos típicamente fluyen en una sola dirección: del padre al hijo. Este flujo de datos unidireccional hace que las aplicaciones sean predecibles y más fáciles de depurar—siempre sabes dónde vive el estado y cómo cambia. Svelte adopta esta filosofía por defecto, pero reconoce que ciertos patrones se benefician genuinamente de la comunicación bidireccional.

La runa $bindable en Svelte 5 proporciona una vía de escape controlada del flujo de datos unidireccional, permitiendo que las props sean enlazadas de modo que los cambios en el componente hijo puedan fluir de vuelta al padre. Este no es un patrón al que recurrir casualmente—el uso excesivo genera un flujo de datos impredecible y componentes difíciles de mantener. Pero cuando se usa con moderación e intención, $bindable puede simplificar drásticamente el código que de otro modo requeriría props de callback verbosas.

Este tutorial explora $bindable de manera integral: desde la mecánica fundamental hasta patrones avanzados, desde los errores comunes hasta los casos de uso del mundo real. Al final, entenderás no solo cómo usar esta runa, sino cuándo es la herramienta adecuada para el trabajo.

El Problema: Comunicación del Hijo al Padre

Considera construir un componente de entrada de formulario reutilizable. El padre necesita conocer el valor actual, y el hijo gestiona el elemento de entrada real. Sin enlace bidireccional, escribirías:

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

Esto funciona, pero es verboso. Estás declarando dos props (value y onValueChange), y el padre debe conectar un callback solo para mantener el estado sincronizado. Para una sola entrada, esto es manejable. Para un formulario complejo con docenas de campos, el código repetitivo se multiplica rápidamente.

La runa $bindable ofrece una alternativa más limpia:

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

El padre usa bind:value para establecer una conexión bidireccional. Los cambios en la entrada de TextInput actualizan automáticamente username en App. El código del componente hijo es más simple, y la intención del padre es más clara.

Sintaxis Básica y Mecánica

La runa $bindable marca una prop como capaz de enlace bidireccional. Se usa dentro de la desestructuración de $props():

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

Características Clave

Enlace opcional: Marcar una prop como $bindable significa que puede ser enlazada, no que deba serlo. Los padres aún pueden pasar props regulares (no enlazadas).
Valores de respaldo: Puedes proporcionar un valor por defecto que aplica cuando no se pasa ninguna prop:

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

Mutación permitida: A diferencia de las props regulares, las props enlazables pueden mutarse dentro del componente hijo, y esas mutaciones fluyen de vuelta al padre.

La Decisión del Padre

El componente padre decide si enlazar:

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

Esta flexibilidad es crucial—el mismo componente puede usarse tanto en escenarios controlados (enlazados) como no controlados (solo prop).

Cómo `$bindable` Difiere de las Props Regulares

Entender la distinción entre props regulares y props enlazables es esencial para usarlas correctamente.

Props Regulares: Solo Lectura por Convención

Con props regulares, técnicamente puedes reasignarlas dentro del componente hijo, pero esto crea una sustitución local temporal que no afecta al padre:

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

Al hacer clic en el botón del hijo se incrementa el count local, pero parentCount permanece sin cambios. Cuando el padre actualiza parentCount, la sustitución local del hijo se pierde. Este comportamiento es intencional—previene flujos de datos inesperados mientras permite estado local temporal.

Props Enlazables: Comunicación Bidireccional Real

Con $bindable, las mutaciones en el hijo se reflejan inmediatamente en el padre:

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

Ahora ambos botones afectan el mismo valor. El incremento del hijo actualiza parentCount, y el incremento del padre actualiza la visualización del hijo. Sincronización bidireccional verdadera.

Valores de Respaldo: Las Sutilezas

Los valores de respaldo en $bindable tienen un comportamiento específico que difiere de los valores por defecto de las props regulares:

Cuándo Aplican los Respaldos

El valor de respaldo se usa solo cuando:

No se pasa ninguna prop en absoluto
La prop se pasa 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 />

Las Props Enlazadas Deben Tener Valores

Cuando una prop está enlazada (usando bind:), se espera que el padre proporcione un valor definido. Si una prop enlazada recibe undefined teniendo un respaldo, Svelte lanza un error en tiempo de ejecución:

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

Esta estrictez previene situaciones ambiguas donde no está claro si debe aplicar el respaldo o el valor del padre.

Las Props Enlazadas Deben Tener Valores

Cuando usas bind: en una prop, Svelte requiere que el valor del padre esté definido. Si el padre proporciona undefined a una prop enlazada que tiene un respaldo, Svelte lanza un error en tiempo de ejecución. Siempre inicializa tu estado antes de enlazar: let value = $state('').

Las Props No Enlazadas Pueden Ser Undefined

Para las props no enlazadas, undefined simplemente activa el respaldo:

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

Enlace a Propiedades de Objetos y Proxies de Estado

Al trabajar con objetos, $bindable interactúa con el sistema de reactividad de Svelte de maneras importantes.

Enlace a Propiedades de Objetos

Puedes enlazar a propiedades de objetos reactivos:

<!-- 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 entrada se enlaza a una propiedad específica del objeto form. Los cambios en cualquier entrada actualizan la propiedad correspondiente de forma reactiva.

Mutaciones de Proxy de Estado

Cuando un proxy $state se pasa como prop (con o sin vinculación), las mutaciones a ese proxy en el componente hijo afectarán al padre. Sin embargo, existe una distinción crucial:

Sin $bindable: Mutar un prop de proxy de estado genera una advertencia porque el componente hijo está modificando un estado que no le "pertenece":

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

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

Con $bindable: El componente hijo reconoce explícitamente que puede modificar el prop:

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

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

Cuándo Vincular Objetos vs. Primitivos

Considera si necesitas vincular el objeto completo o propiedades 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 propiedades específicas es más explícito y facilita rastrear el flujo de datos. Vincular objetos completos es apropiado cuando el componente hijo gestiona legítimamente el estado del objeto completo.

Casos de Uso en el Mundo Real

1. Componentes de Entrada de Formulario

El caso de uso más común: crear envoltorios reutilizables de entradas:

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

Gestionar el estado abierto/cerrado desde el padre o el hijo:

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

El modal puede cerrarse desde el padre (estableciendo showSettings = false), al hacer clic en el fondo, presionar Escape o hacer clic en el botón de cierre—todo a través del mismo estado vinculado.

3. Paneles Acordeón/Colapsables

Gestionar qué panel 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 Paginación

Sincronizar el estado de página entre el padre y el hijo:

<!-- 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 Pestañas

Gestionar el estado de la pestaña activa:

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

Patrones Avanzados

Múltiples Props Vinculables

Los componentes pueden tener múltiples props vinculables para interacciones complejas:

<!-- 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 Vinculables Calculados: Entrada de Moneda

Un patrón común es transformar los valores a medida que fluyen hacia adentro y hacia afuera. Esta entrada de moneda almacena centavos internamente (evitando problemas de punto flotante) pero muestra dólares formateados:

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

El padre trabaja con centavos (enteros), mientras que los usuarios ven y editan moneda formateada. Este patrón evita los problemas de precisión de punto flotante comunes en aplicaciones financieras.

Valores Vinculables Calculados: Generador de Slug

Otro patrón de transformación práctico: generación automática de slugs de URL a partir de títulos, permitiendo la personalización 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>

Este patrón es esencial para constructores de CMS y blogs: el slug se genera automáticamente a partir del título, pero puede personalizarse manualmente cuando sea necesario.

Vinculable con Validación

Combina la vinculación con validación para entradas controladas:

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

Integración con TypeScript

Tipar correctamente los props vinculables garantiza seguridad de tipos a través de los límites de los 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 complejos:

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

Errores Comunes y Soluciones

1: Olvidar `$bindable` en el Componente Hijo

<!-- 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: Enlazar 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: Abuso de Bindings

Cuando un componente tiene muchas props enlazadas, se vuelve difícil rastrear dónde se originan los cambios de estado. Como guía: enlaza como máximo uno o dos valores por componente. Si te encuentras enlazando más, considera si una única prop de callback estructurada sería más clara.

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

Cuando demasiadas cosas están enlazadas, el flujo de datos se vuelve impredecible. Considera:

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

4: Mutar Props No Enlazables

<!-- 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: Actualizaciones Circulares

Si un $effect lee y luego escribe una prop $bindable, se activará a sí mismo nuevamente en la próxima actualización. Protégete contra esto comparando el nuevo valor con el actual antes de escribir, o reestructura para que la lógica pertenezca a una prop de callback en su lugar.

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

Cuándo Usar `$bindable` vs. Props de Callback

Usa `$bindable` Cuando:

La prop representa estado de UI que tanto el padre como el hijo necesitan leer y escribir (abierto/cerrado, valor seleccionado, página actual)
El enlace es intuitivo y coincide con el funcionamiento de los elementos nativos (<input bind:value>)
La relación es simple — un valor, sincronización bidireccional
Estás construyendo componentes de formulario que envuelven inputs nativos

Usa Props de Callback Cuando:

La acción tiene efectos secundarios más allá de actualizar el estado (llamadas a APIs, analíticas, validación)
El padre necesita interceptar o transformar el cambio antes de aplicarlo
Múltiples valores cambian juntos y deben manejarse de forma atómica
Necesitas prevenir o cancelar ciertas actualizaciones de forma condicional

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

Resumen de Buenas Prácticas

Usa $bindable con moderación — Prefiere el flujo de datos unidireccional; usa el enlace solo cuando genuinamente simplifica tu código.
Siempre proporciona valores de respaldo para props enlazables opcionales para garantizar un comportamiento predecible.
Documenta las props enlazables claramente — Deja en claro qué props soportan enlace.
Valida en los límites — No asumas que los valores enlazados siempre son válidos; valida tanto en el padre como en el hijo cuando sea necesario.
Prefiere enlaces primitivos — Enlazar valores individuales es más claro que enlazar objetos completos.
Considera la accesibilidad — Asegúrate de que los cambios de estado de UI enlazados sean anunciados a los lectores de pantalla cuando corresponda.
Prueba el uso tanto enlazado como no enlazado — Tu componente debería funcionar correctamente independientemente de si el padre enlaza o no.
Evita cadenas de enlace profundas — Si te encuentras enlazando a través de múltiples capas de componentes, reconsidera tu arquitectura.

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

El rune $bindable representa el enfoque reflexivo de Svelte para la comunicación entre componentes — reconociendo que, si bien el flujo de datos unidireccional es el ideal predeterminado, el enlace bidireccional controlado tiene casos de uso legítimos que no deberían requerir soluciones verbosas. Úsalo con criterio, y hará que las APIs de tus componentes sean más limpias e intuitivas. Úsalo en exceso, y te encontrarás depurando cambios de estado impredecibles en toda tu aplicación.

Conclusiones Clave

$bindable es una vía de escape controlada del flujo de datos unidireccional — no es el patrón predeterminado y debe usarse con moderación solo cuando genuinamente simplifica el código.
Marcar una prop como $bindable la hace capaz de enlazarse, no obligatoria — el padre elige si enlazar (bind:value={x}) o pasar unidireccionalmente (value={x}); el mismo componente funciona de ambas formas.
Los valores de respaldo aplican solo cuando no se pasa ninguna prop o el valor es undefined — las props enlazadas que reciben undefined lanzan errores en tiempo de ejecución, mientras que las props no enlazadas usan el respaldo de forma elegante.
Usa $bindable para estado de UI, callbacks para acciones — bindable es ideal para abierto/cerrado, valor seleccionado, página actual; los callbacks son mejores para acciones con efectos secundarios como llamadas a APIs o validación.
Los patrones avanzados incluyen transformaciones calculadas — inputs de moneda que almacenan centavos pero muestran dólares, generadores de slug que crean URLs automáticamente a partir de títulos, y validación que combina enlace con manejo de errores.
Errores comunes a evitar — olvidar $bindable en el hijo (los cambios no fluirán hacia arriba), enlazar valores indefinidos, abusar de los bindings causando flujo de datos impredecible, y crear bucles de actualización circular con $effect.

Flujo de Datos Bidireccional Entre Componentes

El Problema: Comunicación del Hijo al Padre

Sintaxis Básica y Mecánica

Características Clave

La Decisión del Padre

Cómo $bindable Difiere de las Props Regulares

Props Regulares: Solo Lectura por Convención

Props Enlazables: Comunicación Bidireccional Real

Valores de Respaldo: Las Sutilezas

Cuándo Aplican los Respaldos

Las Props Enlazadas Deben Tener Valores

Las Props Enlazadas Deben Tener Valores

Las Props No Enlazadas Pueden Ser Undefined

Enlace a Propiedades de Objetos y Proxies de Estado

Enlace a Propiedades de Objetos

Mutaciones de Proxy de Estado

Cuándo Vincular Objetos vs. Primitivos

Casos de Uso en el Mundo Real

1. Componentes de Entrada de Formulario

2. Componentes de Modal y Diálogo

3. Paneles Acordeón/Colapsables

4. Componentes de Paginación

5. Componentes de Pestañas

Patrones Avanzados

Múltiples Props Vinculables

Valores Vinculables Calculados: Entrada de Moneda

Valores Vinculables Calculados: Generador de Slug

Vinculable con Validación

Integración con TypeScript

Errores Comunes y Soluciones

1: Olvidar $bindable en el Componente Hijo

2: Enlazar Valores Indefinidos

3: Abuso de Bindings

4: Mutar Props No Enlazables

5: Actualizaciones Circulares

Cuándo Usar $bindable vs. Props de Callback

Usa $bindable Cuando:

Usa Props de Callback Cuando:

Resumen de Buenas Prácticas

Referencia Rápida

Conclusiones Clave

Ver También

Documentación Oficial

Recursos Externos

Cómo `$bindable` Difiere de las Props Regulares

1: Olvidar `$bindable` en el Componente Hijo

Cuándo Usar `$bindable` vs. Props de Callback

Usa `$bindable` Cuando: