Depois de dominar os fundamentos de $props, você está pronto para explorar os padrões que impulsionam bibliotecas de componentes e design systems em produção.

Vamos mergulhar de cabeça.

Este artigo aborda padrões avançados. Se você é novo em props no Svelte 5, comece pelo artigo da Rune $props, que cobre os fundamentos como desestruturação, valores padrão, ressalvas sobre reatividade e integração básica com TypeScript.

Rest Props e Encaminhamento de Props

À medida que você constrói bibliotecas de componentes mais sofisticadas, frequentemente surgirá a necessidade de passar props através de um componente para um elemento subjacente ou componente filho. Rest props — a capacidade de capturar "tudo o mais" que não foi explicitamente desestruturado — tornam esse padrão elegante e de fácil manutenção.

Entendendo o Padrão Rest

O operador spread (...) na desestruturação do JavaScript captura todas as propriedades restantes em um novo objeto. No contexto de $props, isso significa que você pode lidar explicitamente com certas props enquanto reúne todo o resto para encaminhamento:

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

A mágica está em {...restProps}. Isso espalha todas as propriedades capturadas no elemento button, tornando-as atributos HTML reais. Qualquer prop que não foi explicitamente desestruturada flui para o elemento subjacente.

Isso significa que o seu componente Button aceita automaticamente qualquer 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>

Todo atributo, exceto variant, passa diretamente para o elemento <button> real. O onclick se torna um manipulador de clique, disabled desabilita o botão, atributos ARIA melhoram a acessibilidade, type e form conectam ao tratamento de formulários, e data-testid viabiliza testes. Seu componente Button não precisa conhecer nenhum desses atributos — ele simplesmente os encaminha.

Por que Rest Props São Essenciais para Bibliotecas de Componentes

Ao construir bibliotecas de componentes ou design systems, rest props não são apenas convenientes — são essenciais. Sem elas, você precisaria declarar explicitamente cada possível atributo HTML que seu wrapper pudesse precisar:

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

Essa abordagem é claramente insustentável. Você perderia atributos, criaria inconsistências e gastaria um esforço enorme mantendo declarações de props em vez 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>

O padrão de rest props não é apenas mais limpo — é mais correto. Seu componente automaticamente suporta todos os atributos válidos, incluindo os que possam ser adicionados ao HTML no futuro.

Construindo um Componente Completo de Input de Formulário

Vamos construir um exemplo mais substancial que demonstra como rest props possibilitam componentes wrapper poderosos. Um componente de input de formulário precisa lidar com labels, erros, textos de ajuda e mais — enquanto ainda suporta todos os atributos nativos de 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 envolve um <input> nativo com funcionalidades de label, tratamento de erros e texto de ajuda. Mas observe que nunca declaramos explicitamente props como type, value, placeholder, maxlength, pattern, min, max, ou quaisquer manipuladores de eventos. Todos eles fluem via 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"
/>

O componente trata as preocupações comuns (label, erro, texto de ajuda, acessibilidade) enquanto permite a personalização completa do input subjacente. Esse é o poder dos rest props — seu wrapper agrega valor sem limitar a flexibilidade.

Encaminhamento Seletivo de Props para Múltiplos Elementos

Às vezes, um único componente contém múltiplos elementos que precisam de props diferentes. Você pode criar múltiplos "buckets" para encaminhamento 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>

Agora os consumidores podem segmentar partes específicas do card:

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

Esse padrão oferece aos consumidores controle refinado sobre cada parte do seu componente, mantendo a API organizada e intuitiva.

Encaminhamento de Manipuladores de Eventos

Rest props lidam com manipuladores de eventos de forma transparente. No Svelte 5, manipuladores de eventos são simplesmente props que começam com on — não são uma sintaxe especial como a diretiva on: do Svelte 4. Isso significa que eles fluem pelos rest props assim como qualquer outro 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>

Qualquer manipulador de evento passado para IconButton funciona automaticamente:

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

O componente não precisa conhecer esses eventos — ele simplesmente os encaminha. Isso torna os componentes wrapper naturais de usar.

Filtrando e Transformando Rest Props

Às vezes, você precisa filtrar ou transformar props antes de encaminhá-las. Talvez você queira impedir que certas props cheguem ao elemento subjacente, ou precise modificar alguns 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 garante que links externos sejam sempre abertos de forma segura (nova aba, sem referrer), enquanto ainda permite que outras props como class, id ou atributos ARIA sejam encaminhadas.

Binding Bidirecional com `$bindable`

Embora o fluxo de dados unidirecional padrão do Svelte (de pai para filho) torne as aplicações mais fáceis de compreender, há casos legítimos em que a comunicação bidirecional simplifica o código. Inputs de formulário são o exemplo clássico — um componente de input precisa tanto receber quanto atualizar um valor. A rune $bindable fornece um mecanismo cuidadosamente projetado para esses cenários.

O Problema que `$bindable` Resolve

Para entender $bindable, vamos primeiro ver o que acontece sem ele. Por padrão, as props fluem em uma única direção — do pai para o filho. Um componente filho pode modificar localmente o valor de uma prop, mas essa mudança não afeta o pai.

Sem binding, modificações no filho não afetam o pai:


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

Adicionando `$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! -->

A diretiva bind: cria o vínculo bidirecional. O valor de fallback (0) só se aplica quando a prop não está vinculada.

Anatomia e Comportamento de $bindable()

A rune $bindable tem uma estrutura e um comportamento específicos que são importantes de entender:

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

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

Distinção crítica sobre fallbacks: O valor de fallback só se aplica quando a prop não está vinculada. Este é um detalhe comportamental 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 -->

Esse comportamento evita uma situação confusa onde não fica claro se o valor de fallback ou o valor vinculado deve ter precedência. Se você estiver usando binding, você deve fornecer um valor.

Construindo um Input de Formulário Real com `$bindable`

Vamos construir um componente de input de texto completo e prático que demonstra o $bindable em ação:

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

O uso é intuitivo e 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 alteração no input reflete imediatamente no estado do componente pai, e qualquer alteração programática no estado do pai atualiza imediatamente o input.

Múltiplas Props Bindable para Componentes Complexos

Componentes podem ter múltiplas props bindable quando gerenciam vários fragmentos de estado relacionados. Um seletor de intervalo de datas é um exemplo perfeito:

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

O componente pai pode fazer binding em ambos os valores e ter controle 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>

Quando Usar `$bindable` vs Props de Callback

Se você estiver sincronizando um único valor que naturalmente flui nos dois sentidos (um campo de texto, uma checkbox, um toggle), use $bindable. Se o pai precisar interceptar, validar ou transformar a alteração antes de aplicá-la — ou se múltiplos valores mudarem atomicamente — use uma prop de callback.

Tanto $bindable quanto props de callback permitem comunicação filho-para-pai, mas servem a propósitos diferentes e têm características distintas. Escolher o padrão certo depende das suas necessidades específicas.

Use $bindable quando:

Você estiver criando inputs semelhantes a formulários que modificam um único valor simples
O pai e o filho devem compartilhar e sincronizar o mesmo estado
Você quiser a sintaxe familiar e idiomática bind: que os desenvolvedores Svelte esperam
A prop representa estado mutável que naturalmente flui em ambas as direções
As alterações devem refletir imediatamente em ambas as direções sem processamento intermediário

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

Use props de callback quando:

Você estiver comunicando eventos ou ações (não sincronizando estado)
O pai precisar decidir como lidar com as alterações (validação, transformação, atualizações condicionais)
Múltiplos valores mudam juntos como parte de uma única operação
Você precisar realizar operações assíncronas antes de aceitar as alterações
A "mudança" é realmente um evento com dados associados, não uma simples atualização 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)}
/>

Uma abordagem híbrida às vezes faz sentido — use $bindable para o valor principal, mas callbacks para 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 Bindable com Estado de Objeto

Quando uma prop bindable é um objeto, as coisas ficam interessantes. O componente filho pode mutar propriedades do objeto e, como é a mesma referência de objeto, essas mutações afetam imediatamente o estado tanto do pai quanto do filho.

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

Isso é poderoso, mas requer consideração cuidadosa. O pai e o filho compartilham o mesmo objeto — não há isolamento. Cada tecla pressionada no filho muta imediatamente o estado do pai.

Para UIs de "editar e salvar", você pode querer trabalhar com uma cópia e propagar as alterações somente em um salvamento explícito:

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

Esse padrão dá aos usuários a capacidade de fazer alterações, visualizá-las e confirmá-las ou descartá-las — sem afetar o estado do pai até que seja explicitamente salvo.

Padrões Avançados de TypeScript

A integração com TypeScript vai além da tipagem básica de props. Vamos explorar padrões para componentes complexos.

Tipando Rest Props

Importar HTMLButtonAttributes (ou qualquer tipo HTML*Attributes) de svelte/elements e estender sua interface Props fornece ao TypeScript conhecimento completo de cada atributo válido para o elemento subjacente — incluindo manipuladores de eventos, atributos ARIA e atributos de dados.

Para componentes wrapper, estenda tipos de elementos HTML de 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>

Agora o TypeScript valida todos os atributos do botão:

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

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

Tipando Snippets

O tipo Snippet de svelte habilita slots de conteúdo 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?.()}

Os consumidores obtêm inferência 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>

Tipagem de Manipuladores de Eventos

Tipifique os manipuladores com precisão para melhor autocompletar:

<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

Generics permitem que componentes funcionem com qualquer tipo de dado mantendo segurança de tipos completa.

Componente Genérico Básico

Você não precisa especificar o parâmetro de tipo no local de chamada — o TypeScript infere T a partir da prop items que você passa. Isso significa que seu componente genérico é totalmente seguro em tipos sem nenhuma anotação extra do 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>

O TypeScript infere T a partir do 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} />

Generics com Restrições

Exija que os itens tenham propriedades 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>

Agora o TypeScript impõe a restrição:

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

Padrões Arquiteturais

Esses padrões resolvem desafios complexos de design de componentes.

Props com Union Discriminada

Quando um componente possui múltiplos "modos" com props obrigatórias 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}

O TypeScript garante que você só acesse propriedades válidas para cada modo.

Componentes Compostos com Context

Componentes relacionados que compartilham 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>

Validação em Tempo de Execução com Effects

O TypeScript captura erros em tempo de compilação. Para validação em tempo de execução:

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

Use $effect para esse tipo de validação reativa e ajuste de valores — ele é executado após cada mudança de estado, que é exatamente quando você precisa inspecionar e corrigir valores. Reserve $effect.pre para casos em que você precisa ler o DOM antes de o Svelte aplicar suas atualizações pendentes, como capturar a posição de rolagem antes de uma lista ser re-renderizada.

Principais Aprendizados

Esses padrões avançados desbloqueiam todo o poder do sistema de props do Svelte 5:

Rest Props & Forwarding permitem o encaminhamento transparente de atributos, essencial para componentes de wrapper e design systems.

$bindable cria vinculações bidirecionais controladas para componentes semelhantes a formulários, mantendo a propriedade clara dos dados.

TypeScript Avançado com tipos de elementos HTML, generics de Snippet e extensões de interface fornece segurança em tempo de compilação para componentes complexos.

Componentes Genéricos permitem reutilização com segurança de tipos para diferentes tipos de dados.

Padrões Arquiteturais como unions discriminadas e componentes compostos resolvem desafios reais de design.

Domine esses padrões e você construirá componentes Svelte 5 que são flexíveis, seguros em relação a tipos e prontos para produção.

Rest Props e Encaminhamento de Props

Entendendo o Padrão Rest

Por que Rest Props São Essenciais para Bibliotecas de Componentes

Construindo um Componente Completo de Input de Formulário

Encaminhamento Seletivo de Props para Múltiplos Elementos

Encaminhamento de Manipuladores de Eventos

Filtrando e Transformando Rest Props

Binding Bidirecional com `$bindable`

O Problema que `$bindable` Resolve

Adicionando `$bindable`

Anatomia e Comportamento de $bindable()

Construindo um Input de Formulário Real com `$bindable`

Múltiplas Props Bindable para Componentes Complexos

Quando Usar `$bindable` vs Props de Callback

Props Bindable com Estado de Objeto

Padrões Avançados de TypeScript

Tipando Rest Props

Tipando Snippets

Tipagem de Manipuladores de Eventos

Componentes Genéricos

Componente Genérico Básico

Generics com Restrições

Múltiplos Parâmetros Genéricos

Padrões Arquiteturais

Props com Union Discriminada

Componentes Compostos com Context

Validação em Tempo de Execução com Effects

Principais Aprendizados

Veja Também

Documentação Oficial

Recursos Externos

Rest Props e Encaminhamento de Props

Entendendo o Padrão Rest

Por que Rest Props São Essenciais para Bibliotecas de Componentes

Construindo um Componente Completo de Input de Formulário

Encaminhamento Seletivo de Props para Múltiplos Elementos

Encaminhamento de Manipuladores de Eventos

Filtrando e Transformando Rest Props

Binding Bidirecional com $bindable

O Problema que $bindable Resolve

Adicionando $bindable

Anatomia e Comportamento de $bindable()

Construindo um Input de Formulário Real com $bindable

Múltiplas Props Bindable para Componentes Complexos

Quando Usar $bindable vs Props de Callback

Props Bindable com Estado de Objeto

Padrões Avançados de TypeScript

Tipando Rest Props

Tipando Snippets

Tipagem de Manipuladores de Eventos

Componentes Genéricos

Componente Genérico Básico

Generics com Restrições

Múltiplos Parâmetros Genéricos

Padrões Arquiteturais

Props com Union Discriminada

Componentes Compostos com Context

Validação em Tempo de Execução com Effects

Principais Aprendizados

Veja Também

Documentação Oficial

Recursos Externos

Binding Bidirecional com `$bindable`

O Problema que `$bindable` Resolve

Adicionando `$bindable`

Construindo um Input de Formulário Real com `$bindable`

Quando Usar `$bindable` vs Props de Callback