Construindo Componentes Agnósticos a Frameworks

Elementos customizados (web components) permitem criar componentes de UI reutilizáveis que funcionam em qualquer framework—ou sem nenhum framework. São o modelo de componentes nativo do HTML, suportado por todos os navegadores modernos sem necessidade de etapa de build para os consumidores.

O Svelte se destaca na compilação de componentes para elementos customizados, mas há um desafio: como seu componente Svelte se comunica com o mundo externo? Como ele despacha eventos para elementos pai? Como ele acessa seu próprio elemento DOM?

É aí que a rune $host entra. Ela fornece acesso direto ao elemento host do elemento customizado—o nó DOM real—habilitando o despacho adequado de eventos, manipulação de atributos e integração com APIs do navegador como formulários.

Este tutorial cobre tudo, desde o despacho básico de eventos até padrões avançados como integração com formulários via ElementInternals, melhorias de acessibilidade e a resolução dos problemas comuns que os desenvolvedores encontram ao construir elementos customizados com Svelte.

O que é `$host`?

A rune $host é uma função que retorna o elemento host quando um componente Svelte é compilado como um elemento customizado. Ela fornece acesso direto ao nó DOM subjacente, o que é essencial para:

Despachar eventos customizados para elementos pai
Acessar e manipular atributos do host
Integrar com APIs do navegador que requerem referências a elementos DOM
Implementar padrões adequados de acessibilidade

Quando `$host` Funciona?

$host lança um erro em tempo de execução se chamado dentro de um componente Svelte comum. Requer tanto <svelte:options customElement="tag-name"/> no arquivo quanto a opção de compilador customElement: true na configuração do seu build.

$host só funciona quando:

Seu componente tem <svelte:options customElement="tag-name"/> definido
O componente é compilado com a opção de compilador customElement: true

Se você tentar usar $host em um componente Svelte comum, ele lançará um erro.

Sintaxe Básica

<svelte:options customElement="my-component" />

<script>
	// $host() returns the HTMLElement (the custom element itself)
	const host = $host()

	// Now you can use standard DOM APIs
	host.dispatchEvent(new CustomEvent('my-event'))
	host.setAttribute('data-ready', 'true')
	host.classList.add('initialized')
</script>

Despachando Eventos Customizados

O caso de uso mais comum para $host é o despacho de eventos customizados. É assim que seu elemento customizado se comunica com o mundo externo.

Por que Não Usar Apenas `createEventDispatcher`?

Em componentes Svelte comuns, você pode usar o sistema de eventos do Svelte. Mas elementos customizados vivem no DOM—eles precisam despachar eventos DOM reais que qualquer código JavaScript possa ouvir, não eventos específicos do Svelte.

Despacho Básico de Eventos

Aqui está um componente stepper clássico que despacha eventos de incremento e decremento:

<!-- Stepper.svelte -->
<svelte:options customElement="my-stepper" />

<script>
	function dispatch(type) {
		$host().dispatchEvent(new CustomEvent(type))
	}
</script>

<button onclick={() => dispatch('decrement')}>−</button>
<button onclick={() => dispatch('increment')}>+</button>

<style>
	button {
		font-size: 1.5rem;
		padding: 0.5rem 1rem;
		cursor: pointer;
	}
</style>

Usando o componente:

<!-- App.svelte -->
<script>
	import './Stepper.svelte'

	let count = $state(0)
</script>

<my-stepper ondecrement={() => count--} onincrement={() => count++}></my-stepper>

<p>Count: {count}</p>

Observe que <my-stepper> não envolve nenhum conteúdo—está vazio. Isso ocorre porque este componente é autocontido: ele renderiza seus próprios botões internamente. Não há elemento <slot> dentro de Stepper.svelte, portanto o componente não aceita filhos. Se você quisesse criar um componente que envolva conteúdo (como um card ou tooltip), você adicionaria <slot></slot> à marcação do seu componente e então colocaria conteúdo entre as tags de abertura e fechamento.

O elemento <slot> usado em elementos customizados é o slot nativo de Web Components, não o <slot> depreciado do Svelte. Em componentes Svelte 5 comuns, você usaria snippets e { @render } para projeção de conteúdo. No entanto, ao construir elementos customizados, você deve usar o <slot> nativo porque é o que o Shadow DOM do navegador espera.

Ou em JavaScript puro:

<my-stepper></my-stepper>
<p id="count">0</p>

<script type="module">
	import './Stepper.svelte'

	let count = 0
	const stepper = document.querySelector('my-stepper')
	const display = document.querySelector('#count')

	stepper.addEventListener('increment', () => {
		count++
		display.textContent = count
	})

	stepper.addEventListener('decrement', () => {
		count--
		display.textContent = count
	})
</script>

Eventos com Dados (detail)

Eventos customizados podem carregar dados na sua propriedade detail:

<!-- ColorPicker.svelte -->
<svelte:options customElement="color-picker" />

<script>
	let { value = '#000000' } = $props()

	function handleChange(event) {
		const newColor = event.target.value

		$host().dispatchEvent(
			new CustomEvent('colorchange', {
				detail: {
					color: newColor,
					previousColor: value
				},
				bubbles: true, // Event bubbles up the DOM
				composed: true // Event crosses shadow DOM boundary
			})
		)

		value = newColor
	}
</script>

<input type="color" {value} onchange={handleChange} />
<span class="preview" style:background-color={value}></span>

<style>
	.preview {
		display: inline-block;
		width: 2rem;
		height: 2rem;
		border-radius: 4px;
		vertical-align: middle;
		margin-left: 0.5rem;
	}
</style>

Ouvindo o evento:

document.querySelector('color-picker').addEventListener('colorchange', (e) => {
	console.log('New color:', e.detail.color)
	console.log('Previous color:', e.detail.previousColor)
})

Opções de Eventos Explicadas

Ao criar eventos customizados, você tem várias opções:

Opção	Padrão	Descrição
`bubbles`	`false`	Se `true`, o evento sobe pela hierarquia de elementos ancestrais
`composed`	`false`	Se `true`, o evento pode cruzar os limites do shadow DOM
`cancelable`	`false`	Se `true`, o evento pode ser cancelado com `preventDefault()`

Quando usar bubbles: true:

<script>
	// Use bubbles when parent elements need to catch the event
	function notifyParents() {
		$host().dispatchEvent(
			new CustomEvent('status-change', {
				detail: { status: 'complete' },
				bubbles: true,
				composed: true
			})
		)
	}
</script>

Quando usar cancelable: true:

<script>
	function attemptDelete() {
		const event = new CustomEvent('beforedelete', {
			detail: { itemId: 123 },
			cancelable: true,
			bubbles: true,
			composed: true
		})

		$host().dispatchEvent(event)

		// Check if any listener called preventDefault()
		if (!event.defaultPrevented) {
			performDelete()
		}
	}
</script>

Acessando Propriedades do Elemento Host

Além de eventos, $host fornece acesso completo às propriedades e métodos do elemento host.

Lendo Atributos

<svelte:options customElement="themed-button" />

<script>
	import { onMount } from 'svelte'

	let theme = $state('default')

	onMount(() => {
		const host = $host()

		// Read an attribute set on the custom element
		theme = host.getAttribute('data-theme') || 'default'

		// Watch for attribute changes
		const observer = new MutationObserver((mutations) => {
			for (const mutation of mutations) {
				if (mutation.attributeName === 'data-theme') {
					theme = host.getAttribute('data-theme') || 'default'
				}
			}
		})

		observer.observe(host, { attributes: true })

		return () => observer.disconnect()
	})
</script>

<button class="theme-{theme}">
	<slot></slot>
</button>

Manipulando Classes e Estilos

<svelte:options customElement="loading-indicator" />

<script>
	let { loading = false } = $props()

	$effect(() => {
		const host = $host()

		if (loading) {
			host.classList.add('is-loading')
			host.setAttribute('aria-busy', 'true')
		} else {
			host.classList.remove('is-loading')
			host.setAttribute('aria-busy', 'false')
		}
	})
</script>

<div class="spinner" class:visible={loading}></div>
<slot></slot>

Obtendo Estilos Computados

<svelte:options customElement="responsive-grid" />

<script>
	import { onMount } from 'svelte'

	let columns = $state(3)

	onMount(() => {
		const host = $host()

		function updateColumns() {
			const width = host.getBoundingClientRect().width

			if (width < 400) columns = 1
			else if (width < 700) columns = 2
			else columns = 3
		}

		const resizeObserver = new ResizeObserver(updateColumns)
		resizeObserver.observe(host)

		return () => resizeObserver.disconnect()
	})
</script>

<div class="grid" style:--columns={columns}>
	<slot></slot>
</div>

<style>
	.grid {
		display: grid;
		grid-template-columns: repeat(var(--columns), 1fr);
		gap: 1rem;
	}
</style>

Integração com Formulários via ElementInternals

Um dos usos mais poderosos de $host é a integração de elementos customizados com formulários HTML usando a API ElementInternals.

O Problema

Por padrão, elementos customizados não participam do envio de formulários. Se você criar um elemento de input customizado, ele não irá:

Enviar seu valor junto com o formulário
Participar da validação do formulário
Ser redefinido quando o formulário for resetado
Ser acessível ao FormData

A Solução: `ElementInternals`

Usando a opção extend em <svelte:options>, você pode criar elementos customizados associados a formulários:

<!-- CustomInput.svelte -->
<svelte:options
	customElement={{
		tag: 'custom-input',
		props: {
			value: { reflect: true },
			name: { reflect: true, attribute: 'name' },
			required: { reflect: true, type: 'Boolean' }
		},
		extend: (customElementConstructor) => {
			return class extends customElementConstructor {
				static formAssociated = true

				constructor() {
					super()
					this.internals = this.attachInternals()
				}
			}
		}
	}}
/>

<script>
	let { value = '', name = '', required = false, internals } = $props()

	let touched = $state(false)
	let error = $state('')

	// Update form value whenever our value changes
	$effect(() => {
		const host = $host()

		// Set the form value
		internals.setFormValue(value)

		// Validate
		if (required && !value && touched) {
			error = 'This field is required'
			internals.setValidity({ valueMissing: true }, error)
		} else {
			error = ''
			internals.setValidity({})
		}
	})

	function handleInput(event) {
		value = event.target.value
	}

	function handleBlur() {
		touched = true
	}
</script>

<div class="input-wrapper">
	<input type="text" {value} oninput={handleInput} onblur={handleBlur} aria-invalid={!!error} />
	{#if error}
		<span class="error">{error}</span>
	{/if}
</div>

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

	input {
		padding: 0.5rem;
		border: 1px solid #ccc;
		border-radius: 4px;
	}

	input[aria-invalid='true'] {
		border-color: #e74c3c;
	}

	.error {
		color: #e74c3c;
		font-size: 0.875rem;
	}
</style>

Usando em um formulário:

<form id="myForm">
	<custom-input name="username" required></custom-input>
	<custom-input name="email"></custom-input>
	<button type="submit">Submit</button>
</form>

<script>
	document.getElementById('myForm').addEventListener('submit', (e) => {
		e.preventDefault()
		const formData = new FormData(e.target)

		// FormData now includes custom-input values!
		console.log('Username:', formData.get('username'))
		console.log('Email:', formData.get('email'))
	})
</script>

Exemplo Completo de Elemento de Formulário

Aqui está um elemento de seleção personalizado mais completo com integração total ao formulário:

<!-- CustomSelect.svelte -->
<svelte:options
	customElement={{
		tag: 'custom-select',
		shadow: 'open',
		props: {
			value: { reflect: true },
			name: { reflect: true },
			required: { reflect: true, type: 'Boolean' },
			disabled: { reflect: true, type: 'Boolean' }
		},
		extend: (ctor) =>
			class extends ctor {
				static formAssociated = true

				constructor() {
					super()
					this.internals = this.attachInternals()
				}

				// Called when the form is reset
				formResetCallback() {
					this.value = ''
				}

				// Called when form state is restored (e.g., back button)
				formStateRestoreCallback(state) {
					this.value = state
				}

				// Called when disabled state changes via fieldset
				formDisabledCallback(disabled) {
					this.disabled = disabled
				}
			}
	}}
/>

<script>
	let { value = '', name = '', required = false, disabled = false, internals } = $props()
	let { options = [] } = $props()

	let open = $state(false)
	let selectedLabel = $derived(
		options.find((opt) => opt.value === value)?.label || 'Select an option'
	)

	$effect(() => {
		internals.setFormValue(value)

		if (required && !value) {
			internals.setValidity({ valueMissing: true }, 'Please select an option')
		} else {
			internals.setValidity({})
		}
	})

	function select(optionValue) {
		value = optionValue
		open = false

		$host().dispatchEvent(
			new CustomEvent('change', {
				detail: { value: optionValue },
				bubbles: true,
				composed: true
			})
		)
	}

	function handleKeydown(event) {
		if (event.key === 'Enter' || event.key === ' ') {
			open = !open
		} else if (event.key === 'Escape') {
			open = false
		}
	}
</script>

<div
	class="select"
	class:open
	class:disabled
	role="combobox"
	aria-expanded={open}
	aria-haspopup="listbox"
	tabindex={disabled ? -1 : 0}
	onkeydown={handleKeydown}
	onclick={() => !disabled && (open = !open)}
>
	<span class="selected">{selectedLabel}</span>
	<span class="arrow">▼</span>
</div>

{#if open}
	<ul class="options" role="listbox">
		{#each options as option}
			<li role="option" aria-selected={option.value === value} onclick={() => select(option.value)}>
				{option.label}
			</li>
		{/each}
	</ul>
{/if}

<style>
	.select {
		display: flex;
		justify-content: space-between;
		align-items: center;
		padding: 0.5rem;
		border: 1px solid #ccc;
		border-radius: 4px;
		cursor: pointer;
		background: white;
	}

	.select.disabled {
		background: #f5f5f5;
		cursor: not-allowed;
		opacity: 0.6;
	}

	.select:focus {
		outline: 2px solid #3498db;
		outline-offset: 2px;
	}

	.arrow {
		font-size: 0.75rem;
		transition: transform 0.2s;
	}

	.select.open .arrow {
		transform: rotate(180deg);
	}

	.options {
		position: absolute;
		top: 100%;
		left: 0;
		right: 0;
		margin: 0;
		padding: 0;
		list-style: none;
		border: 1px solid #ccc;
		border-radius: 4px;
		background: white;
		box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
		z-index: 100;
	}

	.options li {
		padding: 0.5rem;
		cursor: pointer;
	}

	.options li:hover {
		background: #f0f0f0;
	}

	.options li[aria-selected='true'] {
		background: #3498db;
		color: white;
	}
</style>

Padrões do Mundo Real

Um tooltip que se posiciona em relação ao seu host:

<!-- Tooltip.svelte -->
<svelte:options customElement="tool-tip" />

<script>
	let { text = '', position = 'top' } = $props()

	let visible = $state(false)
	let coords = $state({ x: 0, y: 0 })

	function show() {
		const host = $host()
		const rect = host.getBoundingClientRect()

		switch (position) {
			case 'top':
				coords = { x: rect.left + rect.width / 2, y: rect.top }
				break
			case 'bottom':
				coords = { x: rect.left + rect.width / 2, y: rect.bottom }
				break
			case 'left':
				coords = { x: rect.left, y: rect.top + rect.height / 2 }
				break
			case 'right':
				coords = { x: rect.right, y: rect.top + rect.height / 2 }
				break
		}

		visible = true
	}

	function hide() {
		visible = false
	}

	// Set up event listeners on mount
	$effect(() => {
		const host = $host()

		host.addEventListener('mouseenter', show)
		host.addEventListener('mouseleave', hide)
		host.addEventListener('focus', show)
		host.addEventListener('blur', hide)

		return () => {
			host.removeEventListener('mouseenter', show)
			host.removeEventListener('mouseleave', hide)
			host.removeEventListener('focus', show)
			host.removeEventListener('blur', hide)
		}
	})
</script>

<slot></slot>

{#if visible}
	<div class="tooltip {position}" style:--x="{coords.x}px" style:--y="{coords.y}px" role="tooltip">
		{text}
	</div>
{/if}

<style>
	.tooltip {
		position: fixed;
		left: var(--x);
		top: var(--y);
		background: #333;
		color: white;
		padding: 0.5rem 0.75rem;
		border-radius: 4px;
		font-size: 0.875rem;
		white-space: nowrap;
		pointer-events: none;
		z-index: 1000;
	}

	.tooltip.top {
		transform: translate(-50%, -100%) translateY(-8px);
	}

	.tooltip.bottom {
		transform: translate(-50%, 0) translateY(8px);
	}

	.tooltip.left {
		transform: translate(-100%, -50%) translateX(-8px);
	}

	.tooltip.right {
		transform: translate(0, -50%) translateX(8px);
	}
</style>

Uso:

<tool-tip text="Click to save your progress" position="top">
	<button>Save</button>
</tool-tip>

Um modal que gerencia corretamente o foco e a acessibilidade:

<!-- Modal.svelte -->
<svelte:options customElement="modal-dialog" />

<script>
	let { open = false, title = '' } = $props()

	let previouslyFocused = $state(null)
	let dialogRef = $state(null)

	$effect(() => {
		if (open) {
			// Store currently focused element
			previouslyFocused = document.activeElement

			// Focus the dialog
			requestAnimationFrame(() => {
				dialogRef?.focus()
			})

			// Prevent body scroll
			document.body.style.overflow = 'hidden'

			// Notify that modal opened
			$host().dispatchEvent(new CustomEvent('open', { bubbles: true }))
		} else if (previouslyFocused) {
			// Restore focus
			previouslyFocused.focus()
			previouslyFocused = null

			// Restore body scroll
			document.body.style.overflow = ''

			// Notify that modal closed
			$host().dispatchEvent(new CustomEvent('close', { bubbles: true }))
		}
	})

	function close() {
		$host().dispatchEvent(
			new CustomEvent('requestclose', {
				bubbles: true,
				cancelable: true
			})
		)
	}

	function handleKeydown(event) {
		if (event.key === 'Escape') {
			close()
		}
	}

	function handleBackdropClick(event) {
		if (event.target === event.currentTarget) {
			close()
		}
	}
</script>

{#if open}
	<div class="backdrop" onclick={handleBackdropClick} onkeydown={handleKeydown}>
		<div
			class="dialog"
			role="dialog"
			aria-modal="true"
			aria-labelledby="dialog-title"
			tabindex="-1"
			bind:this={dialogRef}
		>
			<header>
				<h2 id="dialog-title">{title}</h2>
				<button class="close-btn" onclick={close} aria-label="Close dialog"> × </button>
			</header>
			<div class="content">
				<slot></slot>
			</div>
			<footer>
				<slot name="footer"></slot>
			</footer>
		</div>
	</div>
{/if}

<style>
	.backdrop {
		position: fixed;
		inset: 0;
		background: rgba(0, 0, 0, 0.5);
		display: flex;
		align-items: center;
		justify-content: center;
		z-index: 1000;
	}

	.dialog {
		background: white;
		border-radius: 8px;
		box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
		max-width: 90vw;
		max-height: 90vh;
		overflow: auto;
		min-width: 300px;
	}

	.dialog:focus {
		outline: none;
	}

	header {
		display: flex;
		justify-content: space-between;
		align-items: center;
		padding: 1rem;
		border-bottom: 1px solid #eee;
	}

	header h2 {
		margin: 0;
		font-size: 1.25rem;
	}

	.close-btn {
		background: none;
		border: none;
		font-size: 1.5rem;
		cursor: pointer;
		padding: 0.25rem 0.5rem;
		line-height: 1;
	}

	.content {
		padding: 1rem;
	}

	footer {
		padding: 1rem;
		border-top: 1px solid #eee;
		display: flex;
		justify-content: flex-end;
		gap: 0.5rem;
	}

	footer:empty {
		display: none;
	}
</style>

Uso:

<modal-dialog id="confirm" title="Confirm Action">
	<p>Are you sure you want to proceed?</p>
	<div slot="footer">
		<button onclick="this.closest('modal-dialog').open = false">Cancel</button>
		<button onclick="handleConfirm()">Confirm</button>
	</div>
</modal-dialog>

<button onclick="document.getElementById('confirm').open = true">Open Modal</button>

3: Componente Accordion

Um accordion com suporte adequado a ARIA:

<!-- Accordion.svelte -->
<svelte:options customElement="ui-accordion" />

<script>
	let { multiple = false } = $props()
	let openPanels = $state(new Set())

	function toggle(panelId) {
		if (openPanels.has(panelId)) {
			openPanels.delete(panelId)
		} else {
			if (!multiple) {
				openPanels.clear()
			}
			openPanels.add(panelId)
		}

		// Force reactivity update
		openPanels = new Set(openPanels)

		$host().dispatchEvent(
			new CustomEvent('toggle', {
				detail: {
					panelId,
					open: openPanels.has(panelId),
					openPanels: [...openPanels]
				},
				bubbles: true
			})
		)
	}

	function isOpen(panelId) {
		return openPanels.has(panelId)
	}

	// Expose methods on the host element
	$effect(() => {
		const host = $host()

		host.open = (panelId) => {
			if (!openPanels.has(panelId)) {
				toggle(panelId)
			}
		}

		host.close = (panelId) => {
			if (openPanels.has(panelId)) {
				toggle(panelId)
			}
		}

		host.toggle = toggle

		host.isOpen = isOpen
	})
</script>

<div class="accordion" role="tablist">
	<slot {toggle} {isOpen}></slot>
</div>

<style>
	.accordion {
		border: 1px solid #ddd;
		border-radius: 4px;
		overflow: hidden;
	}
</style>

<!-- AccordionPanel.svelte -->
<svelte:options customElement="accordion-panel" />

<script>
	let { id, title, open = false } = $props()

	function handleClick() {
		// Find parent accordion and tell it to toggle this panel
		const accordion = $host().closest('ui-accordion')
		accordion?.toggle?.(id)
	}

	function handleKeydown(event) {
		if (event.key === 'Enter' || event.key === ' ') {
			event.preventDefault()
			handleClick()
		}
	}
</script>

<div class="panel" class:open>
	<button
		class="header"
		onclick={handleClick}
		onkeydown={handleKeydown}
		aria-expanded={open}
		aria-controls="panel-{id}"
		id="header-{id}"
	>
		<span>{title}</span>
		<span class="icon">{open ? '−' : '+'}</span>
	</button>

	<div class="content" id="panel-{id}" role="region" aria-labelledby="header-{id}" hidden={!open}>
		<div class="inner">
			<slot></slot>
		</div>
	</div>
</div>

<style>
	.panel {
		border-bottom: 1px solid #ddd;
	}

	.panel:last-child {
		border-bottom: none;
	}

	.header {
		width: 100%;
		display: flex;
		justify-content: space-between;
		align-items: center;
		padding: 1rem;
		background: #f9f9f9;
		border: none;
		cursor: pointer;
		font-size: 1rem;
		text-align: left;
	}

	.header:hover {
		background: #f0f0f0;
	}

	.content {
		overflow: hidden;
		transition: max-height 0.3s ease;
	}

	.content[hidden] {
		display: none;
	}

	.inner {
		padding: 1rem;
	}

	.icon {
		font-weight: bold;
	}
</style>

Problemas Comuns e Soluções

1: `$host` É Indefinido

Problema: Você está recebendo um erro informando que $host é indefinido ou não pode ser chamado.

Causa: Você está usando $host em um componente que não foi compilado como um elemento customizado.

Solução:

<!-- AVOID: Missing customElement option -->
<script>
	const host = $host() // Error!
</script>

<!-- PREFERRED: Add the customElement option -->
<svelte:options customElement="my-component" />

<script>
	const host = $host() // Works!
</script>

Verifique também se sua build está configurada corretamente:

// svelte.config.js
export default {
	compilerOptions: {
		customElement: true
	}
}

2: Eventos Não Chegam aos Elementos Pai

Custom events dispatched inside a Shadow DOM do not cross the boundary into the document by default. Set both bubbles: true and composed: true on every event your custom element intends to expose publicly — otherwise parent elements and vanilla JS consumers will never see them.

Problema: Eventos customizados disparados pelo seu componente não estão sendo capturados pelos elementos pai.

Causa: Por padrão, eventos não propagam (bubble) nem cruzam o Shadow DOM.

Solução:

<script>
	function dispatchEvent() {
		// AVOID: Won't reach elements outside shadow DOM
		$host().dispatchEvent(new CustomEvent('myevent'))

		// PREFERRED: Bubbles up AND crosses shadow DOM boundary
		$host().dispatchEvent(
			new CustomEvent('myevent', {
				bubbles: true,
				composed: true
			})
		)
	}
</script>

3: Props Não Acessíveis como Atributos

Problema: Definir atributos no seu elemento customizado não atualiza as props do componente.

Causa: Por padrão, apenas props explicitamente declaradas tornam-se propriedades do elemento.

Solução: Use a configuração props:

<svelte:options
	customElement={{
		tag: 'my-element',
		props: {
			count: { type: 'Number', reflect: true },
			label: { attribute: 'data-label' },
			disabled: { type: 'Boolean', reflect: true }
		}
	}}
/>

<script>
	let { count = 0, label = '', disabled = false } = $props()
</script>

Agora:

<!-- These all work -->
<my-element count="5" data-label="Hello" disabled></my-element>

4: Estilos Vazam para Dentro ou para Fora

Svelte custom elements use an open Shadow DOM by default, which fully encapsulates styles. If you see style leakage, check whether you've explicitly set shadow: 'none' in <svelte:options>. Use CSS custom properties (--my-var) to allow controlled theming from the outside.

Problema: Estilos globais afetam seu componente, ou os estilos do seu componente vazam para fora.

Causa: O encapsulamento do Shadow DOM não está funcionando como esperado.

Solução 1: Garanta que o Shadow DOM esteja habilitado (padrão):

<svelte:options customElement="my-element" />

<!-- Shadow DOM is enabled by default -->

Solução 2: Se você desabilitou o Shadow DOM intencionalmente:

<svelte:options
	customElement={{
		tag: 'my-element',
		shadow: 'none'  <!-- No encapsulation! -->
	}}
/>

<!-- Use unique class names or CSS custom properties -->
<style>
	.my-element-wrapper { /* ... */ }
	.my-element-button { /* ... */ }
</style>

5: Slots Não Funcionam Como Esperado

Problema: O conteúdo inserido via slot é renderizado mesmo quando não deveria, ou não é renderizado múltiplas vezes dentro de {#each}.

Causa: Os slots do DOM funcionam de forma diferente dos slots do Svelte.

Limitações importantes:

O conteúdo inserido via slot sempre é renderizado (mesmo dentro de {#if false})
Slots em {#each} não duplicam o conteúdo

Solução: Projete levando em conta essas limitações:

<!-- Instead of conditionally showing slots... -->
{#if showContent}
	<slot></slot> <!-- Content still renders in DOM! -->
{/if}

<!-- ...use CSS to hide/show -->
<div class:hidden={!showContent}>
	<slot></slot>
</div>

<style>
	.hidden {
		display: none;
	}
</style>

6: Context Não Funciona Entre Elementos Customizados

Problema: setContext em um elemento customizado pai não pode ser lido com getContext em um elemento customizado filho.

Causa: O contexto é baseado em componentes, não no DOM. Cada elemento customizado é uma aplicação Svelte isolada.

Solução: Use comunicação baseada no DOM:

<!-- Parent.svelte -->
<svelte:options customElement="parent-element" />

<script>
	let sharedData = $state({ theme: 'dark' })

	$effect(() => {
		// Expose data on the DOM element
		$host().sharedData = sharedData
	})
</script>

<slot></slot>

<!-- Child.svelte -->
<svelte:options customElement="child-element" />

<script>
	import { onMount } from 'svelte'

	let parentData = $state(null)

	onMount(() => {
		// Find parent and access its data
		const parent = $host().closest('parent-element')
		if (parent) {
			parentData = parent.sharedData
		}
	})
</script>

7: Métodos do Componente Não Disponíveis Imediatamente

Problema: Chamar métodos em um elemento customizado logo após criá-lo falha.

Causa: O componente Svelte interno não é criado até o próximo tick após o connectedCallback.

Solução 1: Aguarde o componente ser montado:

const element = document.createElement('my-element')
document.body.appendChild(element)

// AVOID: Component not ready yet
element.doSomething() // Error!

// PREFERRED: Wait for next tick
await new Promise((resolve) => setTimeout(resolve, 0))
element.doSomething() // Works!

Solução 2: Use a opção extend para métodos sempre disponíveis:

<svelte:options
	customElement={{
		tag: 'my-element',
		extend: (ctor) =>
			class extends ctor {
				// This method is available immediately
				doSomething() {
					// Can queue work for when component mounts
					this._pendingActions = this._pendingActions || []
					this._pendingActions.push(['doSomething', arguments])
				}
			}
	}}
/>

Boas Práticas

1. Sempre Use `bubbles` e `composed` para Eventos Públicos

<script>
	function emitChange(value) {
		$host().dispatchEvent(
			new CustomEvent('change', {
				detail: { value },
				bubbles: true, // Bubbles up the DOM
				composed: true // Crosses shadow DOM
			})
		)
	}
</script>

2. Prefixe os Nomes de Eventos Customizados

Evite conflitos com eventos nativos do DOM:

<script>
	// AVOID: Could conflict with native events
	$host().dispatchEvent(new CustomEvent('change'))

	// PREFERRED: Prefixed to avoid conflicts
	$host().dispatchEvent(new CustomEvent('mycomponent:change'))
</script>

3. Documente a API do Seu Custom Element

Crie um contrato claro para os consumidores:

<!--
	@element my-counter
	@description A simple counter component

	@prop {number} value - Current count value (default: 0)
	@prop {number} min - Minimum allowed value
	@prop {number} max - Maximum allowed value
	@prop {boolean} disabled - Whether the counter is disabled

	@event increment - Fired when count increases
	@event decrement - Fired when count decreases
	@event change - Fired when count changes (detail: { value })

	@method reset() - Reset counter to initial value
	@method setValue(n) - Set counter to specific value
-->
<svelte:options customElement="my-counter" />

4. Use Propriedades CSS Personalizadas para Temas

Permita que os consumidores personalizem a aparência sem quebrar o encapsulamento:

<style>
	button {
		background: var(--button-bg, #3498db);
		color: var(--button-color, white);
		padding: var(--button-padding, 0.5rem 1rem);
		border-radius: var(--button-radius, 4px);
	}
</style>

<style>
	my-button {
		--button-bg: #e74c3c;
		--button-color: white;
	}
</style>

<my-button>Styled Button</my-button>

5. Trate a Limpeza Corretamente

Ao usar $host com event listeners ou observers:

<script>
	$effect(() => {
		const host = $host()
		const handler = () => console.log('clicked')

		host.addEventListener('click', handler)

		// Always clean up!
		return () => {
			host.removeEventListener('click', handler)
		}
	})
</script>

6. Torne os Componentes Progressivamente Aprimorados

Projete componentes que funcionem mesmo antes do JavaScript carregar:

<!-- Works without JS (shows native select) -->
<custom-select>
	<select>
		<option value="a">Option A</option>
		<option value="b">Option B</option>
	</select>
</custom-select>

<!-- CustomSelect.svelte -->
<script>
	import { onMount } from 'svelte'

	let options = $state([])

	onMount(() => {
		// Read options from light DOM
		const select = $host().querySelector('select')
		if (select) {
			options = [...select.options].map((opt) => ({
				value: opt.value,
				label: opt.textContent
			}))
			select.hidden = true
		}
	})
</script>

Referência Rápida

Uso Básico de `$host`

// Get the host element
const host = $host()

// Dispatch events
host.dispatchEvent(
	new CustomEvent('myevent', {
		detail: { data: 'value' },
		bubbles: true,
		composed: true
	})
)

// Access attributes
host.getAttribute('data-id')
host.setAttribute('data-ready', 'true')

// Manipulate classes
host.classList.add('active')
host.classList.remove('loading')

// Access dimensions
host.getBoundingClientRect()

Configuração de Custom Element

<svelte:options
	customElement={{
		tag: 'my-element',
		shadow: 'open', // 'open', 'none'
		props: {
			propName: {
				attribute: 'attr-name', // HTML attribute name
				reflect: true, // Reflect to attribute
				type: 'String' // 'String', 'Number', 'Boolean', 'Array', 'Object'
			}
		},
		extend: (ctor) =>
			class extends ctor {
				// Custom element class extensions
			}
	}}
/>

Custom Element Associado a Formulário

<svelte:options
	customElement={{
		tag: 'form-input',
		extend: (ctor) =>
			class extends ctor {
				static formAssociated = true

				constructor() {
					super()
					this.internals = this.attachInternals()
				}

				formResetCallback() {
					/* ... */
				}
				formStateRestoreCallback(state) {
					/* ... */
				}
				formDisabledCallback(disabled) {
					/* ... */
				}
			}
	}}
/>

<script>
	let { internals } = $props()

	$effect(() => {
		internals.setFormValue(value)
		internals.setValidity(validityState, message)
	})
</script>

Pontos-Chave

A rune $host desbloqueia todo o poder dos custom elements no Svelte:

$host() retorna o elemento host — Acesso direto ao nó do DOM para APIs web padrão.
Despache eventos DOM reais — Use CustomEvent com bubbles e composed para propagação adequada de eventos.
Integração com formulários via ElementInternals — Crie elementos de formulário personalizados que participam completamente em formulários HTML.
Acesse propriedades e atributos do host — Leia, escreva e observe alterações nos atributos do custom element.
Encapsulamento com Shadow DOM — Estilos e DOM são encapsulados por padrão, com propriedades CSS personalizadas para temas.
Saída agnóstica de framework — Seus componentes Svelte se tornam web components padrão utilizáveis em qualquer lugar.

Custom elements são uma maneira poderosa de criar componentes reutilizáveis e encapsulados que funcionam entre frameworks e em HTML puro. Com o $host e o suporte a custom elements do Svelte, você pode criar componentes que:

São agnósticos de framework e podem ser usados em qualquer ambiente web
Têm estilos e comportamento encapsulados com Shadow DOM
Se integram perfeitamente com formulários HTML usando ElementInternals
Oferecem uma ótima experiência de desenvolvimento com a reatividade e compilação do Svelte
Podem ser publicados como pacotes independentes no npm ou usados diretamente no navegador
Custom elements com Shadow DOM têm estilos isolados, evitando conflitos de CSS e reduzindo os custos de recálculo de estilos

Custom elements são perfeitos para sistemas de design, widgets incorporáveis e qualquer componente que precise funcionar entre diferentes frameworks ou em HTML puro. Com $host e a excelente compilação do Svelte, você obtém o melhor dos dois mundos: uma ótima experiência de desenvolvimento e componentes verdadeiramente portáveis.