O Que São Props?

Props (abreviação de "properties", ou propriedades) são a principal forma de passar dados de um componente pai para um componente filho no Svelte. Pense nas props como as entradas do seu componente — assim como uma função recebe argumentos, um componente recebe props.

No Svelte 4 e versões anteriores, as props eram declaradas usando export let. Embora inteligente, essa abordagem tinha limitações — ela espalhava declarações por todo o código e tornava a integração com TypeScript desafiadora. A rune $props do Svelte 5 centraliza o tratamento de props em um único objeto desestruturável que torna a interface do seu componente imediatamente visível.

Quando você usa um componente no Svelte, cada atributo que você coloca na tag do componente se torna uma prop que o componente filho pode acessar:

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

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

No Svelte 5, a rune $props é como você acessa essas props dentro do seu componente. Ela retorna um objeto contendo todos os valores passados pelo pai:

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

Esse mecanismo simples impulsiona toda a comunicação de pai para filho em aplicações Svelte.

Por Que as Props São Importantes

Entender props é fundamental para construir aplicações Svelte, pois elas definem como seus componentes se comunicam. Props bem projetadas criam:

Interfaces de Componentes Claras: Props declaram quais dados um componente precisa, tornando óbvio como usar o componente corretamente.

Componentes Reutilizáveis: Ao aceitar props, um único componente pode exibir conteúdo diferente com base nos dados que recebe.

Fluxo de Dados Previsível: Os dados fluem em uma direção — do pai para o filho — tornando sua aplicação mais fácil de entender e depurar.

Segurança de Tipos: Com TypeScript, as props podem ser totalmente tipadas, capturando erros antes que seu código seja executado.

Vamos explorar como usar $props de forma eficaz, começando com o padrão mais importante: a desestruturação.

Props Básicas com Desestruturação

Embora você possa acessar props como props.name, props.price, etc., isso rapidamente se torna verboso. A sintaxe de desestruturação do JavaScript oferece uma abordagem mais limpa que também serve como documentação para a interface do seu 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>

Quando o pai usa esse componente:

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

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

A desestruturação { title, cookTime, difficulty, ingredients } extrai esses quatro valores do objeto de props, tornando-os disponíveis como variáveis normais no seu componente.

Por Que a Desestruturação É Preferida

Desestruturação não é apenas sobre código mais curto — ela cria componentes autodocumentados:

Desestruturar props tem custo zero em tempo de execução — o compilador do Svelte a otimiza durante a build.

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

Qualquer pessoa que leia seu componente pode ver instantaneamente quais props ele espera observando a instrução de desestruturação. Essa explicitude melhora a manutenibilidade e torna a refatoração mais segura.

Valores Padrão para Props

Frequentemente, você quer que as props tenham valores de fallback quando o pai não as fornece. A sintaxe de desestruturação do JavaScript suporta valores padrão com o 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>

Agora o pai pode fornecer apenas as props que lhe interessam:

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

Quando os Padrões São Aplicados

Os valores padrão se aplicam somente quando a prop é undefined. Isso é importante de entender — valores falsy como null, false, 0 ou string vazia "" NÃO acionam os padrões:

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

Esse comportamento é intencional. Quando um pai passa explicitamente 0, false ou uma string vazia, ele tem essa intenção. Os padrões são verdadeiramente para quando nenhum valor é fornecido.

Valores Padrão Complexos

Os padrões na desestruturação do JavaScript não se limitam a valores primitivos. Você pode usar objetos, arrays, funções e até expressões complexas. Essa flexibilidade permite designs 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>

Esse padrão é incrivelmente poderoso para criar componentes com comportamento padrão rico. O componente DataTable acima funciona imediatamente com zero configuração, mas cada aspecto pode ser personalizado passando a prop apropriada. Essa "divulgação progressiva de complexidade" é uma marca registrada de APIs de componentes bem projetadas.

Importante: Objetos Padrão Não São Reativos

Aqui está um dos comportamentos mais importantes — e comumente mal compreendidos — no sistema de props do Svelte 5: valores de objeto padrão para props não vinculáveis não são convertidos em proxies de estado reativo. Isso significa que, se um componente pai não fornecer uma prop e seu componente usar seu valor de objeto padrão, mutações nesse objeto não acionarão reatividade:

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

Vamos acompanhar exatamente o que acontece em diferentes cenários:

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

Esse comportamento existe por boas razões. Tornar cada valor padrão automaticamente reativo teria implicações de performance e poderia levar a situações confusas onde objetos são inesperadamente compartilhados entre instâncias de componentes. Em vez disso, o Svelte oferece controle explícito sobre a reatividade.

Como lidar com essa situação: Se o seu componente precisa mutar um objeto prop internamente, você tem várias opções:

Use $bindable para criar uma vinculação bidirecional (abordado em detalhes mais adiante)
Crie estado reativo local derivado da 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>

Use props de callback para comunicar mudanças de volta ao pai:

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

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

Entender essa ressalva é essencial para evitar bugs sutis em suas aplicações Svelte 5. Em caso de dúvida, lembre-se: se você precisa mutar um objeto prop, use $bindable ou crie estado local.

Renomeando Props com Desestruturação

A sintaxe de desestruturação do JavaScript permite que você renomeie propriedades ao extraí-las, e essa capacidade é inestimável ao trabalhar com props. Existem dois cenários principais onde a renomeação se torna necessária: quando um nome de prop conflita com uma palavra reservada do JavaScript, e quando você quer usar um nome diferente internamente para maior clareza.

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

Esse padrão é especialmente importante ao criar componentes wrapper para elementos HTML. O HTML possui atributos como class, for e outros que colidem com palavras reservadas do JavaScript. Ao renomear durante a desestruturação, você mantém uma API limpa para os consumidores (eles usam nomes de atributos HTML padrão) enquanto evita erros de sintaxe na sua implementação.

A sintaxe originalName: newName = defaultValue pode parecer complexa a princípio, mas se decompõe logicamente: você está dizendo "pegue a propriedade chamada originalName, chame-a de newName neste escopo e, se ela não existir, use defaultValue."

Props Obrigatórias vs Opcionais

Props sem valores padrão são implicitamente obrigatórias—se o componente pai não as fornecer, elas serão undefined:

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

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

Para usuários de TypeScript, essa distinção se torna explícita nas definições de tipo:

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

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

O TypeScript avisará se um componente pai usar seu componente sem fornecer as props obrigatórias.

Passando Diferentes Tipos de Dados

Props podem passar qualquer valor JavaScript—primitivos, objetos, arrays, funções e mais:

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

A Sintaxe Abreviada

Quando o nome da prop coincide com o nome de uma variável, você pode usar a abreviação {variable} em vez 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} />

Essa abreviação mantém seus templates mais limpos quando os nomes das variáveis coincidem com os nomes das props.

Valores Padrão Condicionais Baseados em Outras Props

Às vezes você precisa de um valor padrão que dependa de outra prop. Infelizmente, não é possível referenciar diretamente outras props dentro dos padrões de desestruturação—o JavaScript avalia todos os padrões antes de a atribuição de desestruturação ser concluída. No entanto, você pode lidar com esse padrão 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}" />

Neste exemplo, o imageSrc é calculado com base em se src foi fornecido. Se o pai passar uma prop src, esse valor é usado. Caso contrário, geramos uma URL de avatar placeholder baseada no nome do usuário. A rune $derived garante que esse cálculo seja reativo—se src ou name mudar, imageSrc é atualizado automaticamente.

Esse padrão mantém a declaração de props limpa (você pode ver de relance quais props o componente aceita) enquanto permite uma lógica de padrão sofisticada no corpo do componente.

Padrões em Camadas para Configuração Complexa

Ao criar componentes com muitas opções de configuração, um padrão comum é mesclar a configuração fornecida pelo usuário com os padrões. Isso permite que os usuários substituam apenas as opções específicas que lhes interessam:

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

Agora os usuários podem personalizar apenas as partes que lhes interessam:

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

Essa abordagem em camadas para os padrões é particularmente valiosa para componentes complexos onde o objeto de configuração completo pode ter dezenas de opções. Os usuários não precisam conhecer ou especificar cada opção—eles fornecem apenas as personalizações de que precisam, e padrões sensatos cuidam de todo o resto.

Entendendo a Reatividade das Props

Props no Svelte são reativas—quando um pai atualiza um valor, o componente filho recebe automaticamente o novo 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 você move o controle deslizante no pai, o display do filho também é atualizado. Essa reatividade é automática—você não precisa fazer nada de especial.

Fluxo de Dados Unidirecional

Props recebidas de $props() são somente leitura. Tentar atribuir diretamente a uma prop desestruturada produzirá um aviso em tempo de execução do Svelte. Use props de callback para sinalizar intenção para cima, ou $bindable para sincronização bidirecional genuína.

Por padrão, os dados fluem em uma direção: do pai para o filho. Props recebidas de $props() são somente leitura — o Svelte 5 avisará em tempo de execução se você tentar atribuir a elas diretamente. Se você precisar comunicar uma mudança de volta ao pai, use uma prop de callback ou $bindable (abordado posteriormente).

O exemplo a seguir demonstra o padrão correto para sinalizar intenção para cima por meio de um 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)} />

Esse fluxo unidirecional torna as aplicações mais fáceis de entender—você sempre sabe de onde os dados vêm. Quando você precisar de comunicação bidirecional, o Svelte fornece a rune $bindable (abordada no artigo Advanced Props Patterns).

Passando Manipuladores de Eventos como Props

No Svelte 5, manipuladores de eventos são simplesmente props de função. Passe-os como qualquer outra 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)}
/>

O pai fornece as funções manipuladoras, e o filho as anexa aos elementos apropriados. Esse padrão dá ao pai controle total sobre como os eventos são tratados.

Chamando Manipuladores com Segurança

Quando uma prop de manipulador é opcional, use encadeamento opcional para chamá-la com segurança. A sintaxe ?.() chama a função somente se ela existir—sem necessidade de um wrapper condicional:

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

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

Integração com TypeScript

TypeScript e $props funcionam juntos perfeitamente. Adicione lang="ts" à sua tag de script e anote suas 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>

O TypeScript fornece:

Autocompletar: Seu editor sugere props válidas ao usar o componente.

Detecção de Erros: Detecte erros de digitação e incompatibilidades de tipo em tempo de compilação.

Documentação: A interface serve como documentação viva da API do seu componente.

Anotações de Tipo Inline

Para componentes mais simples, você pode definir o tipo inline:

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

No entanto, interfaces nomeadas são geralmente preferidas por legibilidade e reutilizabilidade.

A Prop `children` e Snippets

Quando você coloca conteúdo entre as tags de abertura e fechamento de um componente, ele fica disponível como uma prop especial children—um "snippet" tipado que o Svelte passa automaticamente. Você o renderiza com {@render children?.()}. O ?.() lida com segurança com os casos em que o pai não fornece nenhum filho.

Isso substitui completamente o antigo elemento <slot> do Svelte 4. Não existe <slot> no 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>

O conteúdo que você aninha dentro de <Panel> é compilado em um snippet e passado ao componente como children. O componente decide onde—e se—renderizá-lo.

Children com TypeScript

Para tipar a prop children, importe o 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>

Gerando IDs Únicos com `$props.id()`

$props.id() gera um ID que é estável entre renderização no servidor e no cliente e único para cada instância do componente. Isso evita incompatibilidades de hidratação e colisões de IDs quando um componente é usado várias vezes na mesma página.

Acessibilidade frequentemente requer vincular elementos com IDs únicos. A função $props.id() gera IDs que são únicos para cada instância do componente e estáveis entre renderização servidor/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 instância deste componente recebe seus próprios IDs únicos, evitando conflitos quando o componente é usado várias vezes em uma página.

Padrões Comuns e Boas Práticas

1: Objetos de Configuração

Para componentes com muitas opções, considere agrupar props relacionados em um objeto de configuração:

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

Isso permite que os usuários substituam apenas opções específicas:

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

2: Valores Computados a partir de Props

Use $derived para calcular valores baseados em 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>

Valores derivados são atualizados automaticamente quando seus props de origem mudam.

3: Validando Props em Tempo de Execução

Embora o TypeScript capture erros de tipo em tempo de compilação, você pode precisar de validação em tempo de execução para dados 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} />

Erros Comuns a Evitar

1: Mutando Props de Objetos

Props no Svelte 5 são somente leitura. Atribuir diretamente a um prop desestruturado ou mutá-lo produzirá um aviso em tempo de execução e não propagará de volta para o pai. Use um prop de callback para comunicar a intenção ao componente pai:

<!-- 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: Esquecendo o Comportamento de Valores Padrão

Lembre-se de que os padrões só se aplicam para undefined:

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

3: Não Usar TypeScript para Props Complexos

Para qualquer componente não trivial, o TypeScript detecta erros de digitação e incompatibilidades de tipo antes que cheguem ao navegador. Um nome de prop escrito incorretamente torna-se silenciosamente undefined em tempo de execução — o TypeScript o identifica imediatamente no local de uso:

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

Principais Conclusões

A rune $props é sua porta de entrada para a comunicação entre componentes no Svelte 5:

Use desestruturação para criar interfaces de componente claras e autodocumentadas
Forneça valores padrão para props opcionais para tornar os componentes flexíveis
Renomeie props quando necessário para evitar conflitos com palavras reservadas
Lembre-se de que a reatividade flui em uma direção — do pai para o filho por padrão
Passe manipuladores de eventos como props de função para comportamento controlado pelo pai
Adicione TypeScript para segurança de tipos e melhor experiência do desenvolvedor
Use $props.id() para gerar IDs únicos acessíveis

Para padrões mais avançados — incluindo rest props, vinculação bidirecional com $bindable, componentes genéricos e padrões complexos de TypeScript — consulte o artigo Padrões Avançados de Props.

O Que São Props?

Por Que as Props São Importantes

Props Básicas com Desestruturação

Por Que a Desestruturação É Preferida

Valores Padrão para Props

Quando os Padrões São Aplicados

Valores Padrão Complexos

Importante: Objetos Padrão Não São Reativos

Renomeando Props com Desestruturação

Props Obrigatórias vs Opcionais

Passando Diferentes Tipos de Dados

A Sintaxe Abreviada

Valores Padrão Condicionais Baseados em Outras Props

Padrões em Camadas para Configuração Complexa

Entendendo a Reatividade das Props

Fluxo de Dados Unidirecional

Passando Manipuladores de Eventos como Props

Chamando Manipuladores com Segurança

Integração com TypeScript

Anotações de Tipo Inline

A Prop `children` e Snippets

Children com TypeScript

Gerando IDs Únicos com `$props.id()`

Padrões Comuns e Boas Práticas

1: Objetos de Configuração

2: Valores Computados a partir de Props

3: Validando Props em Tempo de Execução

Erros Comuns a Evitar

1: Mutando Props de Objetos

2: Esquecendo o Comportamento de Valores Padrão

3: Não Usar TypeScript para Props Complexos

Principais Conclusões

Veja Também

Documentação Oficial

Recursos Externos

O Que São Props?

Por Que as Props São Importantes

Props Básicas com Desestruturação

Por Que a Desestruturação É Preferida

Valores Padrão para Props

Quando os Padrões São Aplicados

Valores Padrão Complexos

Importante: Objetos Padrão Não São Reativos

Renomeando Props com Desestruturação

Props Obrigatórias vs Opcionais

Passando Diferentes Tipos de Dados

A Sintaxe Abreviada

Valores Padrão Condicionais Baseados em Outras Props

Padrões em Camadas para Configuração Complexa

Entendendo a Reatividade das Props

Fluxo de Dados Unidirecional

Passando Manipuladores de Eventos como Props

Chamando Manipuladores com Segurança

Integração com TypeScript

Anotações de Tipo Inline

A Prop children e Snippets

Children com TypeScript

Gerando IDs Únicos com $props.id()

Padrões Comuns e Boas Práticas

1: Objetos de Configuração

2: Valores Computados a partir de Props

3: Validando Props em Tempo de Execução

Erros Comuns a Evitar

1: Mutando Props de Objetos

2: Esquecendo o Comportamento de Valores Padrão

3: Não Usar TypeScript para Props Complexos

Principais Conclusões

Veja Também

Documentação Oficial

Recursos Externos

A Prop `children` e Snippets

Gerando IDs Únicos com `$props.id()`