Una vez que domines los conceptos básicos de $props, estarás listo para explorar los patrones que potencian las bibliotecas de componentes y sistemas de diseño en producción.

Comencemos.

Este artículo cubre patrones avanzados. Si eres nuevo en los props de Svelte 5, comienza con el artículo Runa $props, que cubre los fundamentos como la desestructuración, valores por defecto, advertencias sobre reactividad e integración básica con TypeScript.

Rest Props y Reenvío de Props

A medida que construyes bibliotecas de componentes más sofisticadas, frecuentemente necesitarás pasar props a través de un componente hacia un elemento subyacente o un componente hijo. Los rest props —la capacidad de capturar "todo lo demás" que no fue desestructurado explícitamente— hacen que este patrón sea elegante y fácil de mantener.

Entendiendo el Patrón Rest

El operador spread (...) en la desestructuración de JavaScript captura todas las propiedades restantes en un nuevo objeto. En el contexto de $props, esto significa que puedes manejar explícitamente ciertos props mientras reúnes todo lo demás para reenviarlo:

<!-- Button.svelte -->
<script>
	let {
		variant = 'primary',
		size = 'medium',
		children,
		...restProps // Captures everything else
	} = $props()

	// restProps now contains all props except variant, size, and children
	// This might include: onclick, disabled, aria-label, type, form, etc.

	const variantClasses = {
		primary: 'bg-blue-500 text-white hover:bg-blue-600',
		secondary: 'bg-gray-200 text-gray-800 hover:bg-gray-300',
		danger: 'bg-red-500 text-white hover:bg-red-600',
		ghost: 'bg-transparent text-gray-700 hover:bg-gray-100'
	}

	const sizeClasses = {
		small: 'px-2 py-1 text-sm',
		medium: 'px-4 py-2',
		large: 'px-6 py-3 text-lg'
	}
</script>

<button
	class="rounded font-medium transition-colors {variantClasses[variant]} {sizeClasses[size]}"
	{...restProps}
>
	{@render children?.()}
</button>

La magia aquí está en {...restProps}. Esto expande todas las propiedades capturadas sobre el elemento button, convirtiéndolas en atributos HTML reales. Cualquier prop que no fue desestructurado explícitamente fluye hacia el elemento subyacente.

Esto significa que tu componente Button acepta automáticamente cualquier atributo válido de button:

<Button
	variant="primary"
	onclick={() => saveDocument()}
	disabled={isLoading}
	aria-busy={isLoading}
	aria-label="Save the current document"
	type="submit"
	form="document-form"
	data-testid="save-button"
>
	Save Changes
</Button>

Cada atributo excepto variant pasa al elemento <button> real. El onclick se convierte en un manejador de clic, disabled deshabilita el botón, los atributos ARIA mejoran la accesibilidad, type y form se conectan al manejo de formularios, y data-testid habilita las pruebas. Tu componente Button no necesita conocer ninguno de estos —simplemente los reenvía.

Por Qué los Rest Props Son Esenciales para las Bibliotecas de Componentes

Al construir bibliotecas de componentes o sistemas de diseño, los rest props no son solo convenientes —son esenciales. Sin ellos, necesitarías declarar explícitamente cada posible atributo HTML que tu wrapper pueda necesitar:

<!-- AVOID: WITHOUT rest props - tedious, incomplete, and maintenance nightmare -->
<script>
	let {
		variant,
		// Now we need to manually declare EVERY possible button attribute...
		onclick,
		ondblclick,
		onmousedown,
		onmouseup,
		onmouseenter,
		onmouseleave,
		onfocus,
		onblur,
		onkeydown,
		onkeyup,
		onkeypress,
		disabled,
		type,
		autofocus,
		form,
		formaction,
		formenctype,
		formmethod,
		formnovalidate,
		formtarget,
		name,
		value,
		ariaLabel,
		ariaDescribedby,
		ariaBusy,
		ariaExpanded,
		ariaHaspopup,
		ariaPressed,
		ariaDisabled,
		tabindex,
		title,
		id,
		// ... dozens more attributes
		// And we'd need to update this list for every new attribute!
		children
	} = $props()
</script>

<button
	{onclick}
	{disabled}
	{type}
	aria-label={ariaLabel}
	<!--
	...manually
	pass
	every
	single
	attribute!!!!
	--
>
	>
	{@render children?.()}
</button>

Este enfoque claramente no es sostenible. Omitirías atributos, crearías inconsistencias y gastarías un esfuerzo enorme manteniendo declaraciones de props en lugar de construir funcionalidades.

<!-- PREFERRED: WITH rest props - clean, complete, and future-proof -->
<script>
	let { variant, children, ...props } = $props()
</script>

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

El patrón de rest props no es solo más limpio —es más correcto. Tu componente soporta automáticamente cualquier atributo válido, incluidos los que podrían agregarse a HTML en el futuro.

Construyendo un Componente Completo de Input para Formularios

Construyamos un ejemplo más sustancial que demuestre cómo los rest props permiten crear componentes wrapper poderosos. Un componente de input para formularios necesita manejar etiquetas, errores, texto de ayuda y más —mientras sigue soportando todos los atributos nativos del input:

<!-- FormInput.svelte -->
<script>
	let {
		// Props specific to our wrapper component
		id, // Required for accessibility
		label,
		error,
		helpText,
		required = false,
		containerClass = '',

		// Everything else passes through to the input
		...inputProps
	} = $props()

	// Determine input state for styling
	let hasError = $derived(!!error)
	let showHelp = $derived(!!helpText && !error)
</script>

<div class="form-field {containerClass}">
	{#if label}
		<label for={id} class="block text-sm font-medium text-gray-700 mb-1">
			{label}
			{#if required}
				<span class="text-red-500 ml-0.5" aria-hidden="true">*</span>
			{/if}
		</label>
	{/if}

	<input
		{id}
		class="
			w-full px-3 py-2 border rounded-md shadow-sm
			focus:outline-none focus:ring-2 focus:ring-offset-0
			{hasError
			? 'border-red-500 focus:ring-red-500'
			: 'border-gray-300 focus:ring-blue-500 focus:border-blue-500'}
		"
		aria-invalid={hasError}
		aria-describedby={hasError ? `${id}-error` : showHelp ? `${id}-help` : undefined}
		{required}
		{...inputProps}
	/>

	{#if hasError}
		<p id="{id}-error" class="mt-1 text-sm text-red-600" role="alert">
			{error}
		</p>
	{:else if showHelp}
		<p id="{id}-help" class="mt-1 text-sm text-gray-500">
			{helpText}
		</p>
	{/if}
</div>

Este componente envuelve un <input> nativo con funcionalidades de etiqueta, manejo de errores y texto de ayuda. Pero observa que nunca declaramos explícitamente props como type, value, placeholder, maxlength, pattern, min, max, ni ningún manejador de eventos. Todos estos fluyen a través de inputProps:

<!-- Usage examples showing the flexibility -->

<!-- Text input with validation -->
<FormInput
	label="Email Address"
	type="email"
	placeholder="you@example.com"
	required
	bind:value={email}
	error={emailError}
	helpText="We'll never share your email with anyone"
	autocomplete="email"
/>

<!-- Number input with constraints -->
<FormInput label="Age" type="number" min={0} max={120} step={1} bind:value={age} />

<!-- Date input with custom handling -->
<FormInput
	label="Appointment Date"
	type="date"
	min={today}
	max={nextMonth}
	bind:value={appointmentDate}
	onchange={(e) => validateDate(e.target.value)}
/>

<!-- Search with custom styling -->
<FormInput
	type="search"
	placeholder="Search products..."
	bind:value={searchQuery}
	oninput={debounce(handleSearch, 300)}
	containerClass="max-w-md mx-auto"
/>

El componente maneja los aspectos comunes (etiqueta, error, texto de ayuda, accesibilidad) mientras permite la personalización completa del input subyacente. Este es el poder de los rest props —tu wrapper agrega valor sin limitar la flexibilidad.

Reenvío Selectivo de Props a Múltiples Elementos

A veces un solo componente contiene múltiples elementos que necesitan props diferentes. Puedes crear múltiples "contenedores" para el reenvío de props:

<!-- Card.svelte -->
<script>
	let {
		// Content props
		title,
		subtitle,
		children,

		// Props specifically for different parts of the card
		headerProps = {},
		bodyProps = {},
		footerProps = {},
		footer,

		// Props for the outer container
		...containerProps
	} = $props()
</script>

<article class="card rounded-lg shadow-md overflow-hidden" {...containerProps}>
	<header class="card-header px-6 py-4 bg-gray-50 border-b" {...headerProps}>
		<h2 class="text-xl font-semibold text-gray-900">{title}</h2>
		{#if subtitle}
			<p class="mt-1 text-sm text-gray-600">{subtitle}</p>
		{/if}
	</header>

	<div class="card-body px-6 py-4" {...bodyProps}>
		{@render children?.()}
	</div>

	{#if footer}
		<footer class="card-footer px-6 py-4 bg-gray-50 border-t" {...footerProps}>
			{@render footer()}
		</footer>
	{/if}
</article>

Ahora los consumidores pueden apuntar a partes específicas de la tarjeta:

<Card
	title="User Profile"
	subtitle="Manage your account settings"
	id="profile-card"
	data-section="user"
	headerProps={{
		class: 'bg-blue-50 border-blue-200',
		'data-testid': 'profile-header'
	}}
	bodyProps={{
		class: 'min-h-[200px]'
	}}
	footerProps={{
		class: 'flex justify-end gap-2'
	}}
>
	<p>Card body content here...</p>

	{#snippet footer()}
		<button class="btn-secondary">Cancel</button>
		<button class="btn-primary">Save</button>
	{/snippet}
</Card>

Este patrón da a los consumidores un control detallado sobre cada parte de tu componente mientras mantiene la API organizada e intuitiva.

Reenvío de Manejadores de Eventos

Los rest props manejan los manejadores de eventos sin problemas. En Svelte 5, los manejadores de eventos son simplemente props que comienzan con on —no son sintaxis especial como la directiva on: de Svelte 4. Esto significa que fluyen a través de los rest props igual que cualquier otro atributo:

<!-- IconButton.svelte -->
<script>
	let {
		icon,
		label,
		size = 'medium',
		...props // Includes onclick, onmouseenter, onfocus, etc.
	} = $props()

	const sizeClasses = {
		small: 'p-1',
		medium: 'p-2',
		large: 'p-3'
	}

	const iconSizes = {
		small: 16,
		medium: 20,
		large: 24
	}
</script>

<button
	class="icon-button rounded-full hover:bg-gray-100 transition-colors {sizeClasses[size]}"
	aria-label={label}
	{...props}
>
	<Icon name={icon} size={iconSizes[size]} />
</button>

Cualquier manejador de eventos pasado a IconButton funciona automáticamente:

<IconButton
	icon="trash"
	label="Delete item"
	onclick={() => deleteItem(id)}
	onmouseenter={() => showTooltip('Delete this item')}
	onmouseleave={() => hideTooltip()}
	onfocus={() => announceForScreenReader('Delete button focused')}
/>

El componente no necesita conocer estos eventos —simplemente los reenvía. Esto hace que los componentes wrapper se sientan nativos al usarlos.

Filtrado y Transformación de Rest Props

A veces necesitas filtrar o transformar props antes de reenviarlos. Quizás quieras evitar que ciertos props lleguen al elemento subyacente, o necesitas modificar algunos valores:

<!-- SafeExternalLink.svelte -->
<script>
	let { href, children, ...props } = $props()

	// Filter out potentially dangerous props
	const {
		onclick, // Remove - we'll handle clicks ourselves
		target, // Remove - we always use _blank
		rel, // Remove - we always use noopener noreferrer
		...safeProps
	} = props

	function handleClick(event) {
		// Log external link clicks for analytics
		trackExternalLink(href)

		// Still call the user's onclick if provided
		onclick?.(event)
	}
</script>

<a {href} target="_blank" rel="noopener noreferrer" onclick={handleClick} {...safeProps}>
	{@render children?.()}
	<span class="external-icon" aria-hidden="true">↗</span>
</a>

Este componente garantiza que los enlaces externos siempre se abran de forma segura (nueva pestaña, sin referrer) mientras permite que otros props como class, id o atributos ARIA pasen libremente.

Enlace Bidireccional con `$bindable`

Aunque el flujo de datos unidireccional predeterminado de Svelte (de padre a hijo) hace que las aplicaciones sean más fáciles de razonar, hay casos legítimos en los que la comunicación bidireccional simplifica el código. Los inputs de formulario son el ejemplo clásico —un componente de input necesita tanto recibir como actualizar un valor. La runa $bindable proporciona un mecanismo cuidadosamente diseñado para estos escenarios.

El Problema que Resuelve `$bindable`

Para entender $bindable, primero veamos qué sucede sin él. Por defecto, los props fluyen en una sola dirección —del padre al hijo. Un componente hijo puede modificar localmente el valor de un prop, pero ese cambio no afecta al padre.

Sin binding, las modificaciones del hijo no afectan al padre:


<script>
	let { rating } = $props();
</script>

<div class="stars">
	{#each [1, 2, 3, 4, 5] as star}
		<button
			class:filled={star <= rating}
			onclick={() => rating = star}
		>
			★
		</button>
	{/each}
</div>

<!-- Parent.svelte -->
<script>
	let userRating = $state(3);
</script>

<RatingInput rating={userRating} />
<p>Your rating: {userRating}</p>
<!-- Clicking stars updates the component display,
    but userRating stays at 3! -->

Agregando `$bindable`

<!-- RatingInput.svelte -->
<script>
	let { rating = $bindable(0) } = $props();
</script>

<div class="stars">
	{#each [1, 2, 3, 4, 5] as star}
		<button
			class:filled={star <= rating}
			onclick={() => rating = star}
		>
			★
		</button>
	{/each}
</div>

<!-- Parent.svelte -->
<script>
	let userRating = $state(3);
</script>

<RatingInput bind:rating={userRating} />
<p>Your rating: {userRating}</p>
<!-- Now clicking stars updates both! -->

La directiva bind: crea el vínculo bidireccional. El valor de respaldo (0) solo se aplica cuando el prop no está enlazado.

Anatomía y Comportamiento de $bindable()

La runa $bindable tiene una estructura y un comportamiento específicos que es importante entender:

<script>
	// $bindable() can include a fallback value
	let { value = $bindable('default') } = $props()

	// Or be used without a fallback
	let { required = $bindable() } = $props()
</script>

Distinción crítica sobre los valores de respaldo: El valor de respaldo solo se aplica cuando el prop no está enlazado. Este es un detalle de comportamiento crucial:

<!-- Parent.svelte -->
<script>
	import Input from './Input.svelte'
	let text = $state('hello')
</script>

<!-- Scenario 1: Prop is bound -->
<Input bind:value={text} />
<!-- 'value' in Input equals 'hello' - the bound value from parent -->

<!-- Scenario 2: Static prop (not bound) -->
<Input value="static text" />
<!-- 'value' in Input equals 'static text' - the provided value -->

<!-- Scenario 3: No prop provided -->
<Input />
<!-- 'value' in Input equals 'default' - the $bindable fallback -->

<!-- Scenario 4: Bound to undefined - THIS THROWS AN ERROR! -->
<Input bind:value={undefined} />
<!-- Runtime error! When binding, parent must provide a defined value -->

Este comportamiento previene una situación confusa donde no queda claro si el valor de respaldo o el valor vinculado deben tener precedencia. Si vas a usar binding, debes proporcionar un valor.

Construyendo un Input de Formulario Real con `$bindable`

Vamos a construir un componente de input de texto completo y práctico que demuestre $bindable en acción:

<!-- TextInput.svelte -->
<script>
	let {
		// The main value - bindable for two-way sync
		value = $bindable(''),

		// Input configuration
		type = 'text',
		placeholder = '',
		disabled = false,
		readonly = false,

		// Validation
		minlength,
		maxlength,
		pattern,
		required = false,

		// Rest props for additional attributes
		...restProps
	} = $props()

	// Computed states for UI feedback
	let isEmpty = $derived(value.trim().length === 0)
	let charCount = $derived(value.length)
	let showCharCount = $derived(maxlength !== undefined)

	// Clear the input
	function clear() {
		value = ''
	}
</script>

<div class="text-input-wrapper">
	<div class="input-container">
		<input
			{type}
			{placeholder}
			{disabled}
			{readonly}
			{minlength}
			{maxlength}
			{pattern}
			{required}
			bind:value
			class="text-input"
			class:empty={isEmpty}
			class:has-clear={!isEmpty && !disabled && !readonly}
			{...restProps}
		/>

		{#if !isEmpty && !disabled && !readonly}
			<button
				type="button"
				class="clear-button"
				onclick={clear}
				aria-label="Clear input"
				tabindex="-1"
			>
				×
			</button>
		{/if}
	</div>

	{#if showCharCount}
		<div class="char-count" class:warning={charCount > maxlength * 0.9}>
			{charCount}/{maxlength}
		</div>
	{/if}
</div>

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

	.input-container {
		position: relative;
		display: flex;
		align-items: center;
	}

	.text-input {
		width: 100%;
		padding: 0.5rem 0.75rem;
		border: 1px solid #d1d5db;
		border-radius: 0.375rem;
		font-size: 1rem;
		transition:
			border-color 0.15s,
			box-shadow 0.15s;
	}

	.text-input:focus {
		outline: none;
		border-color: #3b82f6;
		box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
	}

	.text-input.has-clear {
		padding-right: 2rem;
	}

	.text-input.empty {
		border-color: #e5e7eb;
	}

	.clear-button {
		position: absolute;
		right: 0.5rem;
		background: none;
		border: none;
		color: #9ca3af;
		cursor: pointer;
		padding: 0.25rem;
		font-size: 1.25rem;
		line-height: 1;
		border-radius: 50%;
		transition:
			color 0.15s,
			background-color 0.15s;
	}

	.clear-button:hover {
		color: #4b5563;
		background-color: #f3f4f6;
	}

	.char-count {
		font-size: 0.75rem;
		color: #6b7280;
		text-align: right;
	}

	.char-count.warning {
		color: #f59e0b;
	}
</style>

El uso es intuitivo y poderoso:

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

	let searchQuery = $state('')
	let username = $state('')

	function handleSearch() {
		console.log('Searching for:', searchQuery)
	}
</script>

<form onsubmit={handleSearch}>
	<!-- Basic bound input -->
	<TextInput bind:value={searchQuery} placeholder="Search..." type="search" />

	<!-- With character limit -->
	<TextInput
		bind:value={username}
		placeholder="Choose a username"
		maxlength={20}
		pattern="[a-z0-9_]+"
	/>

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

<!-- Values are always in sync -->
<p>Search query: "{searchQuery}"</p>
<p>Username: "{username}"</p>

Cada cambio en el input se refleja inmediatamente en el estado del padre, y cualquier cambio programático en el estado del padre actualiza inmediatamente el input.

Múltiples Props Vinculables para Componentes Complejos

Los componentes pueden tener múltiples props vinculables cuando gestionan varios fragmentos de estado relacionado. Un selector de rango de fechas es un ejemplo perfecto:

<!-- DateRangePicker.svelte -->
<script>
	let {
		// Both dates are bindable - the component manages a range
		startDate = $bindable(null),
		endDate = $bindable(null),

		// Configuration (not bindable - just configuration)
		minDate = null,
		maxDate = null,
		dateFormat = 'YYYY-MM-DD',

		// Callbacks for additional control
		onrangechange,
		oninvalid
	} = $props()

	// Validation: ensure end is not before start
	$effect(() => {
		if (startDate && endDate && new Date(endDate) < new Date(startDate)) {
			// Auto-correct invalid range
			endDate = startDate
			oninvalid?.({ reason: 'end_before_start', correctedTo: startDate })
		}
	})

	// Calculate range duration
	let rangeDays = $derived.by(() => {
		if (!startDate || !endDate) return null
		const start = new Date(startDate)
		const end = new Date(endDate)
		return Math.round((end - start) / (1000 * 60 * 60 * 24))
	})

	// Notify parent of range changes
	$effect(() => {
		if (startDate && endDate) {
			onrangechange?.({ startDate, endDate, days: rangeDays })
		}
	})
</script>

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

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

	<div class="date-field">
		<label for="end-date">End Date</label>
		<input
			id="end-date"
			type="date"
			bind:value={endDate}
			min={startDate || minDate}
			max={maxDate}
		/>
	</div>

	{#if rangeDays !== null}
		<div class="range-info">
			{rangeDays} day{rangeDays !== 1 ? 's' : ''} selected
		</div>
	{/if}
</div>

El padre puede vincularse a ambos valores y tener control total:

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

	let reportStart = $state('2025-01-01')
	let reportEnd = $state('2025-03-31')

	function handleRangeChange({ startDate, endDate, days }) {
		console.log(`Report covers ${days} days: ${startDate} to ${endDate}`)
	}
</script>

<DateRangePicker
	bind:startDate={reportStart}
	bind:endDate={reportEnd}
	minDate="2020-01-01"
	maxDate="2025-12-31"
	onrangechange={handleRangeChange}
/>

<p>Generating report from {reportStart} to {reportEnd}</p>

<button
	onclick={() => {
		// Programmatically set the range
		reportStart = '2025-06-01'
		reportEnd = '2025-06-30'
	}}
>
	Set to June 2025
</button>

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

Si estás sincronizando un único valor que fluye de forma natural en ambas direcciones (un campo de texto, un checkbox, un toggle), usa $bindable. Si el padre necesita interceptar, validar o transformar el cambio antes de aplicarlo — o si múltiples valores cambian de forma atómica — usa una prop de callback.

Tanto $bindable como las props de callback permiten la comunicación de hijo a padre, pero sirven para propósitos diferentes y tienen características distintas. Elegir el patrón correcto depende de tus necesidades específicas.

Usa $bindable cuando:

Estás creando inputs tipo formulario que modifican un valor único y simple
El padre y el hijo deben compartir y sincronizar el mismo estado
Quieres la sintaxis familiar e idiomática bind: que los desarrolladores de Svelte esperan
La prop representa estado mutable que fluye de forma natural en ambas direcciones
Los cambios deben reflejarse inmediatamente en ambas direcciones sin procesamiento intermedio

<!-- PREFERRED: Good uses of $bindable - simple value synchronization -->
<TextInput bind:value={username} />
<Slider bind:value={volume} min={0} max={100} />
<Toggle bind:checked={darkMode} />
<ColorPicker bind:color={selectedColor} />
<Dropdown bind:selected={country} options={countries} />

Usa props de callback cuando:

Estás comunicando eventos o acciones (no sincronizando estado)
El padre necesita decidir cómo manejar los cambios (validación, transformación, actualizaciones condicionales)
Múltiples valores cambian juntos como parte de una sola operación
Necesitas realizar operaciones asíncronas antes de aceptar los cambios
El "cambio" es realmente un evento con datos asociados, no una actualización simple de valor

<!-- PREFERRED: Good uses of callbacks - events and complex interactions -->
<FileUploader onupload={(files) => processAndStoreFiles(files)} />
<DataGrid
	rows={data}
	onrowselect={(row) => setSelectedRow(row)}
	onrowdelete={(row) => confirmAndDelete(row)}
/>
<Form
	onsubmit={async (data) => {
		const errors = await validateOnServer(data)
		if (errors) return showErrors(errors)
		await saveDataToServer(data)
	}}
	onerror={(e) => logError(e)}
/>
<SearchAutocomplete
	onsearch={(query) => fetchSuggestions(query)}
	onselect={(suggestion) => navigateTo(suggestion.url)}
/>

Un enfoque híbrido a veces tiene sentido—usa $bindable para el valor principal pero callbacks para los eventos:

<!-- ComboBox.svelte -->
<script>
	let {
		// The selected value - bindable for easy two-way sync
		value = $bindable(''),

		// Events that communicate actions, not value changes
		onfocus,
		onblur,
		oninputchange, // When user types (before selection)
		onselect // When user selects from dropdown
	} = $props()
</script>

<!-- Parent.svelte -->
<ComboBox
	bind:value={selectedCity}
	oninputchange={(query) => fetchCitySuggestions(query)}
	onselect={(city) => loadCityDetails(city)}
/>

Props Vinculables con Estado de Objetos

Cuando una prop vinculable es un objeto, las cosas se vuelven interesantes. El componente hijo puede mutar propiedades del objeto, y debido a que es la misma referencia de objeto, esas mutaciones afectan el estado tanto del padre como del hijo de inmediato.

<!-- UserEditor.svelte -->
<script>
	let { user = $bindable({ name: '', email: '', bio: '', role: 'user' }) } = $props()
</script>

<div class="user-editor">
	<label>
		Name
		<input bind:value={user.name} placeholder="Name" />
	</label>

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

	<label>
		Bio
		<textarea bind:value={user.bio} placeholder="Bio"></textarea>
	</label>

	<label>
		Role
		<select bind:value={user.role}>
			<option value="user">User</option>
			<option value="admin">Admin</option>
			<option value="moderator">Moderator</option>
		</select>
	</label>
</div>

<!-- Profile.svelte (parent) -->
<script>
	import UserEditor from './UserEditor.svelte'

	let currentUser = $state({
		name: 'Stan',
		email: 'stan@example.com',
		role: 'admin'
	})
</script>

<UserEditor bind:user={currentUser} />

<!-- Changes in UserEditor immediately reflect here! -->
<pre>{JSON.stringify(currentUser, null, 2)}</pre>

Esto es poderoso pero requiere una consideración cuidadosa. El padre y el hijo comparten el mismo objeto — no hay aislamiento. Cada tecla presionada en el hijo muta inmediatamente el estado del padre.

Para interfaces de usuario de "editar y guardar", puede que quieras trabajar con una copia y solo propagar los cambios al guardar explícitamente:

<!-- SafeUserEditor.svelte -->
<script>
	let {
		user, // The "source of truth" from parent
		onsave, // Called when user clicks save
		oncancel // Called when user cancels
	} = $props()

	// Create a local draft copy for editing
	// Changes to 'draft' don't affect 'user'
	let draft = $state({ ...user })

	// Track if there are unsaved changes
	let hasChanges = $derived(
		draft.name !== user.name ||
			draft.email !== user.email ||
			draft.role !== user.role ||
			draft.bio !== user.bio
	)

	function save() {
		onsave(draft)
	}

	function cancel() {
		// Reset draft to original values
		draft = { ...user }
		oncancel?.()
	}

	function reset() {
		draft = { ...user }
	}
</script>

<div class="user-editor">
	<label>
		Name
		<input bind:value={draft.name} />
	</label>

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

	<label>
		Role
		<select bind:value={draft.role}>
			<option value="user">User</option>
			<option value="admin">Admin</option>
		</select>
	</label>

	<div class="actions">
		<button
			onclick={() => {
				draft = { ...user }
				oncancel?.()
			}}
			disabled={!hasChanges}
		>
			Cancel
		</button>
		<button onclick={reset} disabled={!hasChanges}>Reset</button>
		<button onclick={save} disabled={!hasChanges}>Save Changes</button>
	</div>
</div>

Este patrón le da a los usuarios la capacidad de hacer cambios, previsualizarlos y confirmarlos o descartarlos — sin afectar el estado del padre hasta que se guarde explícitamente.

Patrones Avanzados de TypeScript

La integración con TypeScript va más allá del tipado básico de props. Exploremos patrones para componentes complejos.

Tipado de Props Rest

Importar HTMLButtonAttributes (o cualquier tipo HTML*Attributes) desde svelte/elements y extender tu interfaz Props le da a TypeScript conocimiento completo de cada atributo válido para el elemento subyacente — incluyendo manejadores de eventos, atributos ARIA y atributos de datos.

Para componentes contenedores, extiende los tipos de elementos HTML desde svelte/elements:

<script lang="ts">
	import type { HTMLButtonAttributes } from 'svelte/elements'

	interface Props extends HTMLButtonAttributes {
		variant?: 'primary' | 'secondary' | 'danger'
		loading?: boolean
	}

	let { variant = 'primary', loading = false, children, disabled, ...rest }: Props = $props()
</script>

<button class="btn btn-{variant}" disabled={loading || disabled} {...rest}>
	{#if loading}<span class="spinner"></span>{/if}
	{@render children?.()}
</button>

Ahora TypeScript valida todos los atributos del botón:

<!-- CORRECT-->
<Button type="submit" form="checkout">Submit</Button>

<!-- ERROR -->
<Button potato="yes">Click</Button>

Tipado de Snippets

El tipo Snippet de svelte permite slots de contenido tipados:

<script lang="ts">
	import type { Snippet } from 'svelte'

	interface DataItem {
		id: string
		name: string
		price: number
	}

	interface Props {
		items: DataItem[]
		children?: Snippet
		header?: Snippet<[{ total: number }]>
		row?: Snippet<[item: DataItem, index: number]>
	}

	let { items, children, header, row }: Props = $props()

	let total = $derived(items.reduce((sum, item) => sum + item.price, 0))
</script>

{#if header}
	{@render header({ total })}
{/if}

{#each items as item, i}
	{#if row}
		{@render row(item, i)}
	{:else}
		<div>{item.name}: ${item.price}</div>
	{/if}
{/each}

{@render children?.()}

Los consumidores obtienen inferencia de tipos completa:

<ItemList {items}>
	{#snippet header(info)}
		<h2>Total: ${info.total}</h2>
		<!-- info.total is typed as number -->
	{/snippet}

	{#snippet row(item, index)}
		<div>#{index + 1}: {item.name}</div>
		<!-- item is typed as DataItem -->
	{/snippet}
</ItemList>

Tipado de Manejadores de Eventos

Tipa los manejadores con precisión para un mejor autocompletado:

<script lang="ts">
	interface Props {
		onclose?: () => void
		onclick?: (event: MouseEvent) => void
		onselect?: (item: { id: string; label: string }) => void
		onsubmit?: (data: FormData) => Promise<void>
		validate?: (value: string) => boolean
	}

	let { onclose, onclick, onselect, onsubmit, validate }: Props = $props()
</script>

Componentes Genéricos

Los genéricos permiten que los componentes funcionen con cualquier tipo de dato manteniendo la seguridad de tipos completa.

Componente Genérico Básico

No necesitas especificar el parámetro de tipo en el lugar de llamada — TypeScript infiere T a partir de la prop items que pasas. Esto significa que tu componente genérico tiene seguridad de tipos completa sin ninguna anotación adicional por parte del consumidor.

<script lang="ts" generics="T">
	interface Props {
		items: T[]
		selected?: T | null
		onselect?: (item: T) => void
		renderItem?: (item: T) => string
	}

	let {
		items,
		selected = $bindable(null),
		onselect,
		renderItem = (item) => String(item)
	}: Props = $props()
</script>

<ul class="select-list">
	{#each items as item}
		<li>
			<button
				class:selected={item === selected}
				onclick={() => {
					selected = item
					onselect?.(item)
				}}
			>
				{renderItem(item)}
			</button>
		</li>
	{/each}
</ul>

TypeScript infiere T a partir del uso:

<script lang="ts">
	const fruits = ['apple', 'banana', 'cherry']
	const users = [
		{ id: 1, name: 'Alice' },
		{ id: 2, name: 'Bob' }
	]

	let selectedFruit = $state<string | null>(null)
	let selectedUser = $state<(typeof users)[0] | null>(null)
</script>

<!-- T inferred as string -->
<SelectList items={fruits} bind:selected={selectedFruit} />

<!-- T inferred as { id: number; name: string } -->
<SelectList items={users} bind:selected={selectedUser} renderItem={(u) => u.name} />

Genéricos con Restricciones

Requiere que los elementos tengan propiedades específicas:

<script lang="ts" generics="T extends { id: string; label: string }">
	interface Props {
		items: T[]
		selected?: T | null
		onselect?: (item: T) => void
	}

	let { items, selected = $bindable(null), onselect }: Props = $props()
</script>

<ul>
	{#each items as item (item.id)}
		<li>
			<button
				class:selected={selected?.id === item.id}
				onclick={() => {
					selected = item
					onselect?.(item)
				}}
			>
				{item.label}
			</button>
		</li>
	{/each}
</ul>

Ahora TypeScript aplica la restricción:

<!-- PREFERRED:Valid - has id and label -->
<SelectList
	items={[
		{ id: '1', label: 'Option A', extra: 'data' },
		{ id: '2', label: 'Option B', extra: 'more' }
	]}
/>

<!-- AVOID: Error - missing required properties -->
<SelectList items={[{ name: 'Alice' }]} />

Múltiples Parámetros Genéricos

<script lang="ts" generics="TKey, TValue">
	import type { Snippet } from 'svelte'

	interface Props {
		entries: Map<TKey, TValue> | [TKey, TValue][]
		keyRenderer?: Snippet<[key: TKey]>
		valueRenderer?: Snippet<[value: TValue]>
		onselect?: (key: TKey, value: TValue) => void
	}

	let { entries, keyRenderer, valueRenderer, onselect }: Props = $props()

	let entriesArray = $derived(entries instanceof Map ? [...entries] : entries)
</script>

<table>
	{#each entriesArray as [key, value]}
		<tr onclick={() => onselect?.(key, value)}>
			<td
				>{#if keyRenderer}{@render keyRenderer(key)}{:else}{String(key)}{/if}</td
			>
			<td
				>{#if valueRenderer}{@render valueRenderer(value)}{:else}{String(value)}{/if}</td
			>
		</tr>
	{/each}
</table>

Patrones Arquitectónicos

Estos patrones resuelven desafíos complejos de diseño de componentes.

Props con Uniones Discriminadas

Cuando un componente tiene múltiples "modos" con props requeridas diferentes:

<script lang="ts">
	import type { Snippet } from 'svelte'

	type Props =
		| { mode: 'static'; content: string; html?: boolean }
		| { mode: 'async'; url: string; loading?: Snippet; error?: Snippet<[Error]> }
		| { mode: 'custom'; render: Snippet }

	let props: Props = $props()

	let asyncContent = $state<string | null>(null)
	let asyncError = $state<Error | null>(null)
	let isLoading = $state(false)

	$effect(() => {
		if (props.mode === 'async') {
			isLoading = true
			fetch(props.url)
				.then((r) => r.text())
				.then((text) => {
					asyncContent = text
					isLoading = false
				})
				.catch((err) => {
					asyncError = err
					isLoading = false
				})
		}
	})
</script>

{#if props.mode === 'static'}
	{#if props.html}{@html props.content}{:else}{props.content}{/if}
{:else if props.mode === 'async'}
	{#if isLoading}
		{#if props.loading}{@render props.loading()}{:else}Loading...{/if}
	{:else if asyncError}
		{#if props.error}{@render props.error(asyncError)}{:else}Error: {asyncError.message}{/if}
	{:else}
		{asyncContent}
	{/if}
{:else if props.mode === 'custom'}
	{@render props.render()}
{/if}

TypeScript garantiza que sólo accedas a propiedades válidas para cada modo.

Componentes Compuestos con Contexto

Componentes relacionados que comparten estado:

<!-- Tabs.svelte -->
<script lang="ts" module>
	import { setContext, getContext } from 'svelte';

	const TABS_KEY = Symbol('tabs');

	interface TabsContext {
		activeTab: string;
		setActiveTab: (id: string) => void;
	}

	export function getTabsContext(): TabsContext {
		const ctx = getContext<TabsContext>(TABS_KEY);
		if (!ctx) error('Tab components must be inside <Tabs>');
		return ctx;
	}
</script>

<script lang="ts">
	import type { Snippet } from 'svelte';

	interface Props {
		defaultTab?: string;
		activeTab?: string;
		onchange?: (tabId: string) => void;
		children: Snippet;
	}

	let {
		defaultTab = '',
		activeTab = $bindable(defaultTab),
		onchange,
		children
	}: Props = $props();

	setContext<TabsContext>(TABS_KEY, {
		get activeTab() { return activeTab; },
		setActiveTab(id: string) {
			activeTab = id;
			onchange?.(id);
		}
	});
</script>

<div class="tabs">
	{@render children()}
</div>

<!-- TabButton.svelte -->
<script lang="ts">
	import { getTabsContext } from './Tabs.svelte';
	import type { Snippet } from 'svelte';

	interface Props {
		id: string;
		children: Snippet;
	}

	let { id, children }: Props = $props();
	const tabs = getTabsContext();

	let isActive = $derived(tabs.activeTab === id);
</script>

<button
	class="tab-button"
	class:active={isActive}
	onclick={() => tabs.setActiveTab(id)}
	aria-selected={isActive}
>
	{@render children()}
</button>

<!-- TabPanel.svelte -->
<script lang="ts">
	import { getTabsContext } from './Tabs.svelte';
	import type { Snippet } from 'svelte';

	interface Props {
		id: string;
		children: Snippet;
	}

	let { id, children }: Props = $props();
	const tabs = getTabsContext();

	let isActive = $derived(tabs.activeTab === id);
</script>

{#if isActive}
	<div class="tab-panel" role="tabpanel">
		{@render children()}
	</div>
{/if}

Uso:

<Tabs defaultTab="profile">
	<div class="tab-list">
		<TabButton id="profile">Profile</TabButton>
		<TabButton id="settings">Settings</TabButton>
		<TabButton id="billing">Billing</TabButton>
	</div>

	<TabPanel id="profile">
		<h2>Profile Settings</h2>
		<p>Manage your profile...</p>
	</TabPanel>

	<TabPanel id="settings">
		<h2>App Settings</h2>
		<p>Configure your preferences...</p>
	</TabPanel>

	<TabPanel id="billing">
		<h2>Billing</h2>
		<p>Payment methods...</p>
	</TabPanel>
</Tabs>

Validación en Tiempo de Ejecución con Effects

TypeScript detecta errores en tiempo de compilación. Para validación en tiempo de ejecución:

<script lang="ts">
	interface Props {
		min: number
		max: number
		value?: number
	}

	let { min, max, value = $bindable(min) }: Props = $props()

	$effect(() => {
		if (min > max) {
			console.warn(`RangeSlider: min (${min}) > max (${max})`)
		}
		if (value < min) {
			console.warn(`RangeSlider: clamping value ${value} to min ${min}`)
			value = min
		}
		if (value > max) {
			console.warn(`RangeSlider: clamping value ${value} to max ${max}`)
			value = max
		}
	})
</script>

<input type="range" {min} {max} bind:value />

Usa $effect para este tipo de validación reactiva y ajuste de valores — se ejecuta después de cada cambio de estado, que es exactamente cuando necesitas inspeccionar y corregir valores. Reserva $effect.pre para casos donde necesites leer el DOM antes de que Svelte aplique sus actualizaciones pendientes, como capturar la posición de scroll antes de que una lista se vuelva a renderizar.

Puntos Clave

Estos patrones avanzados desbloquean todo el poder del sistema de props de Svelte 5:

Props Rest y Reenvío permiten el reenvío transparente de atributos, esencial para componentes contenedores y sistemas de diseño.

$bindable crea enlaces bidireccionales controlados para componentes similares a formularios, manteniendo una propiedad clara de los datos.

TypeScript Avanzado con tipos de elementos HTML, genéricos de Snippet y extensiones de interfaces proporciona seguridad en tiempo de compilación para componentes complejos.

Componentes Genéricos permiten reutilización con seguridad de tipos en diferentes tipos de datos.

Patrones Arquitectónicos como uniones discriminadas y componentes compuestos resuelven desafíos de diseño del mundo real.

Domina estos patrones y construirás componentes de Svelte 5 que son flexibles, seguros en cuanto a tipos y listos para producción.

Rest Props y Reenvío de Props

Entendiendo el Patrón Rest

Por Qué los Rest Props Son Esenciales para las Bibliotecas de Componentes

Construyendo un Componente Completo de Input para Formularios

Reenvío Selectivo de Props a Múltiples Elementos

Reenvío de Manejadores de Eventos

Filtrado y Transformación de Rest Props

Enlace Bidireccional con `$bindable`

El Problema que Resuelve `$bindable`

Agregando `$bindable`

Anatomía y Comportamiento de $bindable()

Construyendo un Input de Formulario Real con `$bindable`

Múltiples Props Vinculables para Componentes Complejos

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

Props Vinculables con Estado de Objetos

Patrones Avanzados de TypeScript

Tipado de Props Rest

Tipado de Snippets

Tipado de Manejadores de Eventos

Componentes Genéricos

Componente Genérico Básico

Genéricos con Restricciones

Múltiples Parámetros Genéricos

Patrones Arquitectónicos

Props con Uniones Discriminadas

Componentes Compuestos con Contexto

Validación en Tiempo de Ejecución con Effects

Puntos Clave

Ver También

Documentación Oficial

Recursos Externos

Rest Props y Reenvío de Props

Entendiendo el Patrón Rest

Por Qué los Rest Props Son Esenciales para las Bibliotecas de Componentes

Construyendo un Componente Completo de Input para Formularios

Reenvío Selectivo de Props a Múltiples Elementos

Reenvío de Manejadores de Eventos

Filtrado y Transformación de Rest Props

Enlace Bidireccional con $bindable

El Problema que Resuelve $bindable

Agregando $bindable

Anatomía y Comportamiento de $bindable()

Construyendo un Input de Formulario Real con $bindable

Múltiples Props Vinculables para Componentes Complejos

Cuándo Usar $bindable vs Props de Callback

Props Vinculables con Estado de Objetos

Patrones Avanzados de TypeScript

Tipado de Props Rest

Tipado de Snippets

Tipado de Manejadores de Eventos

Componentes Genéricos

Componente Genérico Básico

Genéricos con Restricciones

Múltiples Parámetros Genéricos

Patrones Arquitectónicos

Props con Uniones Discriminadas

Componentes Compuestos con Contexto

Validación en Tiempo de Ejecución con Effects

Puntos Clave

Ver También

Documentación Oficial

Recursos Externos

Enlace Bidireccional con `$bindable`

El Problema que Resuelve `$bindable`

Agregando `$bindable`

Construyendo un Input de Formulario Real con `$bindable`

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