¿Qué son los Props?

Los props (abreviatura de "properties" o propiedades) son la forma principal de pasar datos de un componente padre a un componente hijo en Svelte. Piensa en los props como las entradas de tu componente—igual que una función recibe argumentos, un componente recibe props.

En Svelte 4 y versiones anteriores, los props se declaraban usando export let. Aunque ingenioso, este enfoque tenía limitaciones—dispersaba las declaraciones por todo el código y dificultaba la integración con TypeScript. La runa $props de Svelte 5 centraliza el manejo de props en un único objeto desestructurable que hace que la interfaz de tu componente sea inmediatamente visible.

Cuando usas un componente en Svelte, cada atributo que colocas en la etiqueta del componente se convierte en un prop al que el componente hijo puede acceder:

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

<!-- These attributes become props inside ProductCard -->
<ProductCard name="Wireless Headphones" price={79.99} inStock={true} />

En Svelte 5, la runa $props es la forma en que accedes a estos props dentro de tu componente. Retorna un objeto que contiene todos los valores pasados desde el padre:

<!-- ProductCard.svelte -->
<script>
	// $props() returns { name: "Wireless Headphones", price: 79.99, inStock: true }
	let props = $props()
</script>

<div class="product">
	<h2>{props.name}</h2>
	<p>${props.price}</p>
	{#if props.inStock}
		<span class="badge">In Stock</span>
	{/if}
</div>

Este simple mecanismo impulsa toda la comunicación de padre a hijo en las aplicaciones Svelte.

Por qué son importantes los Props

Entender los props es fundamental para construir aplicaciones Svelte porque definen cómo se comunican tus componentes. Los props bien diseñados crean:

Interfaces de componentes claras: Los props declaran qué datos necesita un componente, dejando en claro cómo usarlo correctamente.

Componentes reutilizables: Al aceptar props, un único componente puede mostrar contenido diferente según los datos que recibe.

Flujo de datos predecible: Los datos fluyen en una sola dirección—del padre al hijo—haciendo que tu aplicación sea más fácil de entender y depurar.

Seguridad de tipos: Con TypeScript, los props pueden estar completamente tipados, detectando errores antes de que tu código se ejecute.

Exploremos cómo usar $props de manera efectiva, comenzando con el patrón más importante: la desestructuración.

Props básicos con desestructuración

Si bien puedes acceder a los props como props.name, props.price, etc., esto se vuelve rápidamente verboso. La sintaxis de desestructuración de JavaScript proporciona un enfoque más limpio que también sirve como documentación para la interfaz de tu componente.

<!-- RecipeCard.svelte -->
<script>
	// Destructuring extracts named properties from the props object
	let { title, cookTime, difficulty, ingredients } = $props()
</script>

<article class="recipe-card">
	<h2>{title}</h2>
	<div class="meta">
		<span>{cookTime} mins</span>
		<span>{difficulty}</span>
	</div>
	<p>{ingredients.length} ingredients</p>
</article>

Cuando el padre usa este componente:

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

<RecipeCard
	title="Pasta Carbonara"
	cookTime={25}
	difficulty="Medium"
	ingredients={['pasta', 'eggs', 'pecorino', 'guanciale', 'pepper']}
/>

La desestructuración { title, cookTime, difficulty, ingredients } extrae estos cuatro valores del objeto props, haciéndolos disponibles como variables regulares en tu componente.

Por qué se prefiere la desestructuración

La desestructuración no es solo una cuestión de código más corto—crea componentes autodocumentados:

La desestructuración de props no tiene costo en tiempo de ejecución—el compilador de Svelte la optimiza durante la compilación.

<script>
	// Less clear - you must read the template to understand what props exist
	let props = $props();
</script>

<h1>{props.headline} - {props.author}</h1>

<script>
	// PREFERRED: the component's interface is visible immediately
	let { headline, author } = $props();
</script>

<h1>{headline} - {author}</h1>

Cualquier persona que lea tu componente puede ver de inmediato qué props espera mirando la instrucción de desestructuración. Esta explicitud mejora la mantenibilidad y hace que la refactorización sea más segura.

Valores por defecto para Props

Con frecuencia, querrás que los props tengan valores de respaldo cuando el padre no los proporcione. La sintaxis de desestructuración de JavaScript admite valores por defecto con el operador =:

<!-- Alert.svelte -->
<script>
	let { message, type = 'info', dismissible = true, icon = '💡' } = $props()
</script>

<div class="alert alert-{type}">
	<span class="icon">{icon}</span>
	<p>{message}</p>
	{#if dismissible}
		<button class="close">×</button>
	{/if}
</div>

Ahora el padre puede proporcionar solo los props que le interesan:

<!-- All of these work correctly -->
<Alert message="Your changes have been saved" />
<!-- Uses defaults: info type, dismissible, 💡 icon -->

<Alert message="Are you sure?" type="warning" icon="⚠️" />
<!-- Custom type and icon, default dismissible -->

<Alert message="Critical error occurred" type="error" dismissible={false} />
<!-- Custom type, not dismissible, default icon -->

Cuándo se aplican los valores por defecto

Los valores por defecto se aplican solo cuando el prop es undefined. Esto es importante de entender—los valores falsy como null, false, 0 o la cadena vacía "" NO activan los valores por defecto:

<script>
	let { quantity = 1, available = true, label = 'Unnamed Item' } = $props()
</script>

<!-- Usage and resulting values -->
<Component />
<!-- quantity: 1, available: true, label: 'Unnamed Item' -->
<Component quantity={0} />
<!-- quantity: 0 (NOT 1!) -->
<Component available={false} />
<!-- available: false (NOT true!) -->
<Component label="" />
<!-- label: '' (NOT 'Unnamed Item'!) -->
<Component quantity={undefined} />
<!-- quantity: 1 (default applies) -->

Este comportamiento es intencional. Cuando un padre pasa explícitamente 0, false o una cadena vacía, lo hace con intención. Los valores por defecto son verdaderamente para cuando no se proporciona ningún valor.

Valores por defecto complejos

Los valores por defecto en la desestructuración de JavaScript no se limitan a valores primitivos. Puedes usar objetos, arreglos, funciones e incluso expresiones complejas. Esta flexibilidad permite diseños de componentes sofisticados:

<!-- DataTable.svelte -->
<script>
	let {
		// Object default - provides a complete configuration
		config = {
			sortable: true,
			filterable: false,
			pageSize: 10,
			showHeader: true,
			stickyHeader: false
		},

		// Array default - defines default columns if none provided
		columns = ['id', 'name', 'value'],

		// Function default - provides default behavior
		onRowClick = (row) => console.log('Row clicked:', row),

		// Function expression for formatting
		formatDate = (date) => new Date(date).toLocaleDateString(),

		// Computed value using an expression
		pageOptions = [10, 25, 50, 100]
	} = $props()
</script>

<table>
	<thead>
		<tr>
			{#each columns as column}
				<th>{column}</th>
			{/each}
		</tr>
	</thead>
	<!-- Table body implementation would use config, formatDate, etc. -->
</table>

Este patrón es increíblemente poderoso para crear componentes con comportamiento por defecto enriquecido. El componente DataTable anterior funciona de forma inmediata con cero configuración, pero cada aspecto puede personalizarse pasando el prop apropiado. Esta "revelación progresiva de la complejidad" es una característica distintiva de las APIs de componentes bien diseñadas.

Importante: Los objetos por defecto no son reactivos

Este es uno de los comportamientos más importantes—y comúnmente malinterpretados—del sistema de props de Svelte 5: los valores por defecto de objetos para props no enlazables no se convierten en proxies de estado reactivo. Esto significa que si un componente padre no proporciona un prop y tu componente usa su valor de objeto por defecto, las mutaciones a ese objeto no activarán la reactividad:

<!-- CounterWithDefault.svelte -->
<script>
	let { counts = { value: 0 } } = $props()
</script>

<button
	onclick={() => {
		// ⚠️ CRITICAL: This mutation has NO EFFECT when using the default value!
		// The default object { value: 0 } is a plain JavaScript object,
		// not a reactive proxy, so changes to it don't trigger updates
		counts.value += 1
	}}
>
	Count: {counts.value}
</button>

Veamos exactamente qué sucede en diferentes escenarios:

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

	// This creates a reactive state proxy
	let counts = $state({ value: 0 })
</script>

<!-- Scenario 1: Parent provides reactive state -->
<!-- PREFERRED: Works perfectly - counts is a reactive proxy from parent,
     so mutations trigger updates -->
<CounterWithDefault {counts} />

<!-- Scenario 2: No prop provided, uses default -->
<!-- AVOID: Clicking won't update the display - the default object
     { value: 0 } is not reactive -->
<CounterWithDefault />

Este comportamiento existe por buenas razones. Hacer que cada valor por defecto sea automáticamente reactivo tendría implicaciones de rendimiento y podría llevar a situaciones confusas donde los objetos se comparten inesperadamente entre instancias de componentes. En cambio, Svelte te da control explícito sobre la reactividad.

Cómo manejar esta situación: Si tu componente necesita mutar un prop de objeto internamente, tienes varias opciones:

Usa $bindable para crear un enlace bidireccional (cubierto en detalle más adelante)
Crea estado reactivo local derivado del prop:

<script>
	let { initialCounts = { value: 0 } } = $props()

	// Create local reactive state from the prop
	let counts = $state({ ...initialCounts })
</script>

<button onclick={() => counts.value++}>
	Count: {counts.value}
</button>

Usa props de callback para comunicar cambios de vuelta al padre:

<script>
	let { counts = { value: 0 }, onCountChange } = $props()
</script>

<button onclick={() => onCountChange?.({ value: counts.value + 1 })}>
	Count: {counts.value}
</button>

Entender esta advertencia es esencial para evitar errores sutiles en tus aplicaciones Svelte 5. Ante la duda, recuerda: si necesitas mutar un prop de objeto, usa $bindable o crea estado local.

Renombrar Props con desestructuración

La sintaxis de desestructuración de JavaScript te permite renombrar propiedades a medida que las extraes, y esta capacidad es invaluable al trabajar con props. Hay dos escenarios principales donde el renombrado se vuelve necesario: cuando el nombre de un prop entra en conflicto con una palabra reservada de JavaScript, y cuando quieres usar un nombre diferente internamente para mayor claridad.

<!-- NavigationItem.svelte -->
<script>
	let {
		// 'class' is a reserved word in JavaScript, so we rename it to 'className'
		// The parent still passes it as 'class', but we access it as 'className'
		class: className = '',

		// 'for' is also reserved (used in for loops and labels)
		for: htmlFor = '',

		// Sometimes you want a different internal name for clarity
		// Parent passes 'isActive', but internally 'active' is more concise
		isActive: active = false,

		// The 'super' keyword is reserved
		super: superProp = 'default value'
	} = $props()
</script>

<a class="nav-item {className}" class:active for={htmlFor}> </a>

Este patrón es especialmente importante al crear componentes envolventes para elementos HTML. HTML tiene atributos como class, for y otros que colisionan con palabras reservadas de JavaScript. Al renombrar durante la desestructuración, mantienes una API limpia para los consumidores (usan nombres de atributos HTML estándar) mientras evitas errores de sintaxis en tu implementación.

La sintaxis originalName: newName = defaultValue puede parecer compleja al principio, pero se descompone de forma lógica: estás diciendo "toma la propiedad llamada originalName, llámala newName en este ámbito, y si no existe, usa defaultValue."

Props Requeridas vs. Opcionales

Las props sin valores por defecto son implícitamente requeridas—si el padre no las proporciona, serán undefined:

<script>
	let {
		// Required - no default value
		orderId,
		customerName,

		// Optional - has default value
		notes = ''
	} = $props()
</script>

Para quienes usan TypeScript, esta distinción se vuelve explícita en las definiciones de tipos:

<script lang="ts">
	interface Props {
		orderId: string // Required
		customerName: string // Required
		notes?: string // Optional (note the ?)
	}

	let { orderId, customerName, notes = '' }: Props = $props()
</script>

TypeScript advertirá si un componente padre usa tu componente sin proporcionar las props requeridas.

Pasar Diferentes Tipos de Datos

Las props pueden pasar cualquier valor de JavaScript—primitivos, objetos, arreglos, funciones y más:

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

	const user = { name: 'Stan', id: 42 }
	const recentOrders = [
		{ id: 1, total: 59.99 },
		{ id: 2, total: 124.5 }
	]
	const handleLogout = () => console.log('Logging out...')
</script>

<!-- String prop -->
<Dashboard title="Sales Overview" />

<!-- Number prop -->
<Dashboard targetRevenue={50000} />

<!-- Boolean prop -->
<Dashboard showChart={true} />
<Dashboard showChart />
<!-- Shorthand for showChart={true} -->

<!-- Object prop -->
<Dashboard {user} />
<!-- Shorthand for user={user} -->

<!-- Array prop -->
<Dashboard orders={recentOrders} />

<!-- Function prop -->
<Dashboard onLogout={handleLogout} />

La Sintaxis Abreviada

Cuando el nombre de la prop coincide con el nombre de una variable, puedes usar la forma abreviada {variable} en lugar de name={variable}:

<script>
	let title = 'My Dashboard'
	let metrics = [
		/* ... */
	]
	let isLoading = false
</script>

<!-- These are equivalent -->
<Widget {title} {metrics} {isLoading} />
<Widget {title} {metrics} {isLoading} />

Esta sintaxis abreviada mantiene tus plantillas más limpias cuando los nombres de las variables coinciden con los nombres de las props.

Valores por Defecto Condicionales Basados en Otras Props

A veces necesitas un valor por defecto que depende de otra prop. Desafortunadamente, no puedes referenciar directamente otras props dentro de los valores por defecto de la desestructuración—JavaScript evalúa todos los valores por defecto antes de que se complete la asignación de desestructuración. Sin embargo, puedes manejar este patrón de forma elegante usando $derived:

<!-- Avatar.svelte -->
<script>
	let {
		name,
		size = 'medium',
		src = undefined // Explicitly undefined, we'll compute the real default
	} = $props()

	// Use $derived to compute a default based on another prop
	// This creates a reactive value that updates if 'name' or 'src' changes
	let imageSrc = $derived(
		src ?? `https://api.dicebear.com/7.x/initials/svg?seed=${encodeURIComponent(name)}`
	)

	// Size mapping for different avatar sizes
	const sizeMap = {
		small: { class: 'w-8 h-8', fontSize: '0.75rem' },
		medium: { class: 'w-12 h-12', fontSize: '1rem' },
		large: { class: 'w-16 h-16', fontSize: '1.25rem' }
	}

	let sizeConfig = $derived(sizeMap[size])
</script>

<img src={imageSrc} alt="Avatar for {name}" class="rounded-full {sizeConfig.class}" />

En este ejemplo, imageSrc se calcula en función de si se proporcionó src. Si el padre pasa una prop src, ese valor es utilizado. Si no, generamos una URL de avatar de marcador de posición basada en el nombre del usuario. La runa $derived garantiza que este cálculo sea reactivo—si src o name cambian, imageSrc se actualiza automáticamente.

Este patrón mantiene la declaración de tus props limpia (puedes ver de un vistazo qué props acepta el componente) al tiempo que permite una lógica de valores por defecto sofisticada en el cuerpo del componente.

Valores por Defecto en Capas para Configuración Compleja

Al construir componentes con muchas opciones de configuración, un patrón común es combinar la configuración proporcionada por el usuario con los valores por defecto. Esto permite a los usuarios sobreescribir únicamente las opciones específicas que les interesan:

<!-- Chart.svelte -->
<script>
	// Default configuration object
	const defaultConfig = {
		animation: {
			enabled: true,
			duration: 300,
			easing: 'ease-out'
		},
		tooltip: {
			enabled: true,
			format: (value) => value.toLocaleString()
		},
		legend: {
			position: 'bottom',
			visible: true
		},
		colors: ['#3b82f6', '#ef4444', '#22c55e', '#f59e0b']
	}

	let { data, config = {} } = $props()

	// Deep merge user config with defaults
	// This allows users to override nested properties without
	// having to specify the entire config object
	let mergedConfig = $derived({
		animation: { ...defaultConfig.animation, ...config.animation },
		tooltip: { ...defaultConfig.tooltip, ...config.tooltip },
		legend: { ...defaultConfig.legend, ...config.legend },
		colors: config.colors ?? defaultConfig.colors
	})
</script>

Ahora los usuarios pueden personalizar solo las partes que les interesan:

<!-- Only customize animation duration and legend position -->
<Chart
	{data}
	config={{
		animation: { duration: 500 },
		legend: { position: 'right' }
	}}
/>

Este enfoque de valores por defecto en capas es particularmente valioso para componentes complejos donde el objeto de configuración completo puede tener decenas de opciones. Los usuarios no necesitan conocer ni especificar cada opción—solo proporcionan las personalizaciones que necesitan, y los valores por defecto razonables se encargan del resto.

Comprender la Reactividad de las Props

Las props en Svelte son reactivas—cuando un padre actualiza un valor, el componente hijo recibe automáticamente el nuevo valor:

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

	let celsius = $state(20);
</script>

<input type="range" min="-20" max="50" bind:value={celsius} />
<p>Slider: {celsius}°C</p>

<TemperatureDisplay {celsius} />

<!-- TemperatureDisplay.svelte -->
<script>
	let { celsius } = $props();

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

<!-- These update automatically when parent's celsius changes -->
<p>{celsius}°C = {fahrenheit.toFixed(1)}°F</p>

Cada vez que mueves el control deslizante en el padre, la visualización del hijo también se actualiza. Esta reactividad es automática—no necesitas hacer nada especial.

Flujo de Datos Unidireccional

Las props recibidas de $props() son de solo lectura. Intentar asignar directamente a una prop desestructurada producirá una advertencia en tiempo de ejecución de Svelte. Usa props de callback para señalar intención hacia arriba, o $bindable para una sincronización genuina bidireccional.

Por defecto, los datos fluyen en una sola dirección: del padre al hijo. Las props recibidas de $props() son de solo lectura — Svelte 5 advertirá en tiempo de ejecución si intentas asignarles un valor directamente. Si necesitas comunicar un cambio de vuelta al padre, puedes usar una prop de callback o $bindable (cubierto más adelante).

El siguiente ejemplo demuestra el patrón correcto para señalar intención hacia arriba mediante un callback:

<!-- VolumeControl.svelte -->
<script>
	let { volume, onVolumeChange } = $props()
</script>

<!-- Preferred: signal intent to the parent, let it own the state -->
<button onclick={() => onVolumeChange?.(volume + 1)}>
	Increase volume: {volume}
</button>

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

	let volume = $state(50)
</script>

<VolumeControl {volume} onVolumeChange={(v) => (volume = v)} />

Este flujo unidireccional hace que las aplicaciones sean más fáciles de entender—siempre sabes de dónde provienen los datos. Cuando necesitas comunicación bidireccional, Svelte proporciona la runa $bindable (cubierta en el artículo Advanced Props Patterns).

Pasar Manejadores de Eventos como Props

En Svelte 5, los manejadores de eventos son simplemente props de función. Pásalos como cualquier otra prop:

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

	function handleSearch(query) {
		console.log('Searching for:', query);
	}

	function handleFocus() {
		console.log('Search focused');
	}
</script>

<SearchBox
	onsearch={handleSearch}
	onfocus={handleFocus}
/>

<!-- SearchBox.svelte -->
<script>
	let { onsearch, onfocus } = $props();

	let query = $state('');
</script>

<input
	type="search"
	bind:value={query}
	{onfocus}
	onkeydown={(e) => e.key === 'Enter' && onsearch?.(query)}
/>

El padre proporciona las funciones manejadoras, y el hijo las vincula a los elementos correspondientes. Este patrón le da al padre control total sobre cómo se manejan los eventos.

Llamar a los Manejadores de Forma Segura

Cuando una prop de manejador es opcional, usa el encadenamiento opcional para llamarla de forma segura. La sintaxis ?.() llama a la función solo si existe — no se necesita ningún condicional envolvente:

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

<button onclick={() => onselect?.({ id: 1, name: 'Item' })}> Select Item </button>

Integración con TypeScript

TypeScript y $props funcionan juntos sin problemas. Agrega lang="ts" a tu etiqueta script y anota tus props:

<script lang="ts">
	interface Props {
		productId: string
		quantity: number
		notes?: string // Optional
		onAddToCart?: (productId: string, qty: number) => void
	}

	let { productId, quantity, notes = '', onAddToCart }: Props = $props()
</script>

<div class="product-controls">
	<p>Product: {productId}, Qty: {quantity}</p>
	{#if notes}
		<p>Notes: {notes}</p>
	{/if}
	<button onclick={() => onAddToCart?.(productId, quantity)}> Add to Cart </button>
</div>

TypeScript proporciona:

Autocompletado: Tu editor sugiere props válidas al usar el componente.

Detección de Errores: Detecta errores tipográficos y discrepancias de tipos en tiempo de compilación.

Documentación: La interfaz sirve como documentación viva de la API de tu componente.

Anotaciones de Tipo en Línea

Para componentes más simples, puedes escribir el tipo en línea:

<script lang="ts">
	let {
		label,
		value
	}: {
		label: string
		value: number
	} = $props()
</script>

Sin embargo, las interfaces con nombre son generalmente preferidas por su legibilidad y reutilización.

La Prop `children` y los Snippets

Cuando colocas contenido entre las etiquetas de apertura y cierre de un componente, queda disponible como una prop especial children — un "snippet" tipado que Svelte pasa automáticamente. Lo renderizas con {@render children?.()}. El ?.() maneja de forma segura los casos en que el padre no proporciona ningún hijo.

Esto reemplaza por completo al antiguo elemento <slot> de Svelte 4. No existe <slot> en Svelte 5.

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

<div class="panel">
	{@render children?.()}
</div>

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

<Panel>
	<h2>Welcome Back!</h2>
	<p>Your dashboard is ready.</p>
</Panel>

El contenido que anidas dentro de <Panel> se compila en un snippet y se pasa al componente como children. El componente decide dónde — y si — renderizarlo.

Children con TypeScript

Para tipar la prop children, importa el tipo Snippet:

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

	interface Props {
		heading: string
		children?: Snippet
	}

	let { heading, children }: Props = $props()
</script>

<section>
	<h1>{heading}</h1>
	{@render children?.()}
</section>

Generando IDs únicos con `$props.id()`

$props.id() genera un ID que es estable entre el renderizado del servidor y el cliente, y único para cada instancia del componente. Esto previene desajustes de hidratación y colisiones de IDs cuando un componente se usa múltiples veces en la misma página.

La accesibilidad frecuentemente requiere vincular elementos con IDs únicos. La función $props.id() genera IDs que son únicos para cada instancia del componente y estables entre el renderizado del servidor y el cliente:

<script>
	let { label, hint } = $props()

	// Generates a unique ID for this component instance
	const uid = $props.id()
</script>

<div class="field">
	<label for="{uid}-input">{label}</label>
	<input id="{uid}-input" aria-describedby="{uid}-hint" />
	{#if hint}
		<p id="{uid}-hint" class="hint">{hint}</p>
	{/if}
</div>

Cada instancia de este componente obtiene sus propios IDs únicos, evitando conflictos cuando el componente se usa múltiples veces en una página.

Patrones comunes y buenas prácticas

1: Objetos de configuración

Para componentes con muchas opciones, considera agrupar props relacionadas en un objeto de configuración:

<script>
	let {
		items,
		options = {
			sortable: true,
			searchable: false,
			pageSize: 10
		}
	} = $props()

	// Merge with defaults for partial overrides
	let config = $derived({
		sortable: true,
		searchable: false,
		pageSize: 10,
		...options
	})
</script>

Esto permite a los usuarios sobrescribir solo opciones específicas:

<ItemList {items} options={{ pageSize: 25 }} />

2: Valores calculados a partir de props

Usa $derived para calcular valores basados en props:

<script>
	let { items, taxRate } = $props()

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

<p>Subtotal: ${subtotal.toFixed(2)}</p>
<p>Tax: ${tax.toFixed(2)}</p>
<p>Total: ${total.toFixed(2)}</p>

Los valores derivados se actualizan automáticamente cuando cambian sus props fuente.

3: Validando props en tiempo de ejecución

Aunque TypeScript detecta errores de tipo en tiempo de compilación, es posible que necesites validación en tiempo de ejecución para datos dinámicos:

<script>
	let { minValue, maxValue, current } = $props()

	// Validate and warn about invalid states
	// $effect runs after the component is mounted; use it only for side effects
	$effect(() => {
		if (minValue > maxValue) {
			console.warn(`Invalid range: min (${minValue}) > max (${maxValue})`)
		}
	})

	// Clamp current value to valid range
	let clampedValue = $derived(Math.min(Math.max(current, minValue), maxValue))
</script>

<input type="range" min={minValue} max={maxValue} value={clampedValue} />

Errores comunes a evitar

1: Mutar props de objetos

Las props de Svelte 5 son de solo lectura. Asignar directamente a una prop desestructurada o mutarla producirá una advertencia en tiempo de ejecución y no se propagará de vuelta al padre. Usa una prop de callback para comunicar la intención hacia arriba en su lugar:

<!-- Avoid -->
<script>
	let { settings } = $props()

	function toggleDarkMode() {
		settings.darkMode = !settings.darkMode // Warning: prop is read-only
	}
</script>

<!-- Preferred -->
<script>
	let { settings, onSettingsChange } = $props()

	function toggleDarkMode() {
		onSettingsChange({ ...settings, darkMode: !settings.darkMode })
	}
</script>

2: Olvidar el comportamiento de los valores predeterminados

Recuerda que los valores predeterminados solo se aplican para undefined:

<script>
	// If parent passes quantity={0}, quantity will be 0, not 1!
	let { quantity = 1 } = $props()
</script>

3: No usar TypeScript para props complejas

Para cualquier componente no trivial, TypeScript detecta errores tipográficos y desajustes de tipos antes de que lleguen al navegador. Un nombre de prop mal escrito se convierte silenciosamente en undefined en tiempo de ejecución — TypeScript lo muestra inmediatamente en el sitio de llamada:

<!-- ProductCard.svelte -->
<script lang="ts">
	interface Props {
		name: string
	}
	let { name }: Props = $props()
</script>

<!-- App.svelte -->
<!-- TypeScript error: 'naem' does not exist in type Props -->
<ProductCard naem="Widget" />

<!-- Correct -->
<ProductCard name="Widget" />

Conclusiones clave

La runa $props es tu puerta de entrada a la comunicación entre componentes en Svelte 5:

Usa la desestructuración para crear interfaces de componentes claras y autodocumentadas
Proporciona valores predeterminados para props opcionales y hacer los componentes flexibles
Renombra props cuando sea necesario para evitar conflictos con palabras reservadas
Recuerda que la reactividad fluye en una sola dirección—del padre al hijo por defecto
Pasa manejadores de eventos como props de función para comportamiento controlado por el padre
Agrega TypeScript para seguridad de tipos y mejor experiencia de desarrollo
Usa $props.id() para generar IDs únicos accesibles

Para patrones más avanzados—incluyendo rest props, enlace bidireccional con $bindable, componentes genéricos y patrones complejos de TypeScript—consulta el artículo Patrones avanzados de Props.

¿Qué son los Props?

Por qué son importantes los Props

Props básicos con desestructuración

Por qué se prefiere la desestructuración

Valores por defecto para Props

Cuándo se aplican los valores por defecto

Valores por defecto complejos

Importante: Los objetos por defecto no son reactivos

Renombrar Props con desestructuración

Props Requeridas vs. Opcionales

Pasar Diferentes Tipos de Datos

La Sintaxis Abreviada

Valores por Defecto Condicionales Basados en Otras Props

Valores por Defecto en Capas para Configuración Compleja

Comprender la Reactividad de las Props

Flujo de Datos Unidireccional

Pasar Manejadores de Eventos como Props

Llamar a los Manejadores de Forma Segura

Integración con TypeScript

Anotaciones de Tipo en Línea

La Prop `children` y los Snippets

Children con TypeScript

Generando IDs únicos con `$props.id()`

Patrones comunes y buenas prácticas

1: Objetos de configuración

2: Valores calculados a partir de props

3: Validando props en tiempo de ejecución

Errores comunes a evitar

1: Mutar props de objetos

2: Olvidar el comportamiento de los valores predeterminados

3: No usar TypeScript para props complejas

Conclusiones clave

Ver también

Documentación oficial

Recursos externos

¿Qué son los Props?

Por qué son importantes los Props

Props básicos con desestructuración

Por qué se prefiere la desestructuración

Valores por defecto para Props

Cuándo se aplican los valores por defecto

Valores por defecto complejos

Importante: Los objetos por defecto no son reactivos

Renombrar Props con desestructuración

Props Requeridas vs. Opcionales

Pasar Diferentes Tipos de Datos

La Sintaxis Abreviada

Valores por Defecto Condicionales Basados en Otras Props

Valores por Defecto en Capas para Configuración Compleja

Comprender la Reactividad de las Props

Flujo de Datos Unidireccional

Pasar Manejadores de Eventos como Props

Llamar a los Manejadores de Forma Segura

Integración con TypeScript

Anotaciones de Tipo en Línea

La Prop children y los Snippets

Children con TypeScript

Generando IDs únicos con $props.id()

Patrones comunes y buenas prácticas

1: Objetos de configuración

2: Valores calculados a partir de props

3: Validando props en tiempo de ejecución

Errores comunes a evitar

1: Mutar props de objetos

2: Olvidar el comportamiento de los valores predeterminados

3: No usar TypeScript para props complejas

Conclusiones clave

Ver también

Documentación oficial

Recursos externos

La Prop `children` y los Snippets

Generando IDs únicos con `$props.id()`