Construyendo Componentes Independientes del Framework

Los elementos personalizados (web components) te permiten crear componentes de UI reutilizables que funcionan en cualquier framework—o sin ninguno. Son el modelo de componentes nativo de HTML, compatible con todos los navegadores modernos sin necesidad de ningún paso de compilación por parte de los consumidores.

Svelte sobresale compilando componentes a elementos personalizados, pero existe un desafío: ¿cómo se comunica tu componente Svelte con el mundo exterior? ¿Cómo despacha eventos a elementos padre? ¿Cómo accede a su propio elemento DOM?

Ahí es donde entra la runa $host. Proporciona acceso directo al elemento host del elemento personalizado—el nodo DOM real—habilitando el despacho apropiado de eventos, la manipulación de atributos y la integración con APIs del navegador como los formularios.

Este tutorial cubre todo, desde el despacho básico de eventos hasta patrones avanzados como la integración con formularios mediante ElementInternals, mejoras de accesibilidad y la resolución de los problemas comunes que encuentran los desarrolladores al construir elementos personalizados con Svelte.

¿Qué es `$host`?

La runa $host es una función que retorna el elemento host cuando un componente Svelte se compila como elemento personalizado. Te da acceso directo al nodo DOM subyacente, lo cual es esencial para:

Despachar eventos personalizados a elementos padre
Acceder y manipular atributos del host
Integrarse con APIs del navegador que requieren referencias a elementos DOM
Implementar patrones de accesibilidad apropiados

¿Cuándo Funciona `$host`?

$host lanza un error en tiempo de ejecución si se llama dentro de un componente Svelte regular. Requiere tanto <svelte:options customElement="tag-name"/> en el archivo como la opción del compilador customElement: true en tu configuración de build.

$host solo funciona cuando:

Tu componente tiene <svelte:options customElement="tag-name"/> establecido
El componente se compila con la opción del compilador customElement: true

Si intentas usar $host en un componente Svelte regular, lanzará un error.

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

El caso de uso más común para $host es despachar eventos personalizados. Así es como tu elemento personalizado se comunica con el mundo exterior.

¿Por Qué No Puedes Usar Simplemente `createEventDispatcher`?

En componentes Svelte regulares, podrías usar el sistema de eventos de Svelte. Pero los elementos personalizados viven en el DOM—necesitan despachar eventos DOM reales que cualquier código JavaScript pueda escuchar, no eventos específicos de Svelte.

Despacho Básico de Eventos

Aquí hay un componente stepper clásico que despacha eventos de incremento y 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 el componente:

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

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

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

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

Nota que <my-stepper> no envuelve ningún contenido—está vacío. Eso es porque este componente es autocontenido: renderiza sus propios botones internamente. No hay elemento <slot> dentro de Stepper.svelte, por lo que el componente no acepta hijos. Si quisieras crear un componente que envuelva contenido (como una tarjeta o tooltip), agregarías <slot></slot> al markup de tu componente y luego colocarías contenido entre las etiquetas de apertura y cierre.

El elemento <slot> usado en elementos personalizados es el slot nativo de Web Components, no el <slot> obsoleto de Svelte. En componentes regulares de Svelte 5, usarías snippets y { @render } para la proyección de contenido. Sin embargo, al construir elementos personalizados, debes usar el <slot> nativo porque eso es lo que espera el Shadow DOM del navegador.

O en 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 con Datos (detail)

Los eventos personalizados pueden llevar datos en su propiedad 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>

Escuchando el evento:

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

Explicación de las Opciones de Eventos

Al crear eventos personalizados, tienes varias opciones:

Opción	Por defecto	Descripción
`bubbles`	`false`	Si es `true`, el evento se propaga hacia arriba por los ancestros
`composed`	`false`	Si es `true`, el evento puede cruzar límites del shadow DOM
`cancelable`	`false`	Si es `true`, el evento puede cancelarse con `preventDefault()`

Cuándo 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>

Cuándo 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>

Accediendo a las Propiedades del Elemento Host

Más allá de los eventos, $host te da acceso completo a las propiedades y métodos del elemento host.

Leyendo 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 Clases y 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>

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

Integración con Formularios mediante ElementInternals

Uno de los usos más poderosos de $host es integrar elementos personalizados con formularios HTML usando la API ElementInternals.

El Problema

Por defecto, los elementos personalizados no participan en el envío de formularios. Si creas un elemento input personalizado, no va a:

Enviar su valor con el formulario
Participar en la validación del formulario
Restablecerse cuando el formulario se reinicie
Ser accesible para FormData

La Solución: `ElementInternals`

Usando la opción extend en <svelte:options>, puedes crear elementos personalizados asociados a formularios:

<!-- 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 en un formulario:

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

Ejemplo Completo de Elemento de Formulario

Aquí hay un elemento select personalizado más completo con integración total de formulario:

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

Patrones del Mundo Real

Un tooltip que se posiciona relativo a su 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>

Un modal que gestiona correctamente el foco y la accesibilidad:

<!-- 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 Acordeón

Un acordeón con soporte ARIA adecuado:

<!-- 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 Comunes y Soluciones

1: `$host` No Está Definido

Problema: Estás obteniendo un error de que $host no está definido o no puede ser llamado.

Causa: Estás usando $host en un componente que no está compilado como elemento personalizado.

Solución:

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

También asegúrate de que tu compilación esté configurada correctamente:

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

2: Los Eventos No Llegan a los Elementos Padre

Los eventos personalizados despachados dentro de un Shadow DOM no cruzan el límite hacia el documento por defecto. Establece tanto bubbles: true como composed: true en cada evento que tu elemento personalizado pretenda exponer públicamente — de lo contrario, los elementos padre y los consumidores de JS vanilla nunca los verán.

Problema: Los eventos personalizados despachados desde tu componente no están siendo capturados por los elementos padre.

Causa: Los eventos no hacen bubble ni cruzan el Shadow DOM por defecto.

Solución:

<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: Las Props No Son Accesibles como Atributos

Problema: Establecer atributos en tu elemento personalizado no actualiza las props del componente.

Causa: Por defecto, solo las props declaradas explícitamente se convierten en propiedades del elemento.

Solución: Usa la configuración 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>

Ahora:

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

4: Los Estilos Se Filtran Hacia Adentro o Hacia Afuera

Los elementos personalizados de Svelte usan un Shadow DOM abierto por defecto, lo cual encapsula completamente los estilos. Si ves filtración de estilos, verifica si has establecido explícitamente shadow: 'none' en <svelte:options>. Usa propiedades personalizadas de CSS (--my-var) para permitir tematización controlada desde el exterior.

Problema: Los estilos globales afectan tu componente, o los estilos de tu componente se filtran hacia afuera.

Causa: La encapsulación del Shadow DOM no funciona como se esperaba.

Solución 1: Asegúrate de que el Shadow DOM esté habilitado (por defecto):

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

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

Solución 2: Si deshabilitaste el 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: Los Slots No Funcionan como Se Espera

Problema: El contenido con slot se renderiza incluso cuando no debería, o no se renderiza múltiples veces en {#each}.

Causa: Los slots del DOM funcionan de manera diferente a los slots de Svelte.

Limitaciones importantes:

El contenido con slot siempre se renderiza (incluso dentro de {#if false})
Los slots en {#each} no duplican el contenido

Solución: Diseña en torno a estas limitaciones:

<!-- 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: El Contexto No Funciona Entre Elementos Personalizados

Problema: setContext en un elemento personalizado padre no puede ser leído con getContext en un elemento personalizado hijo.

Causa: El contexto está basado en componentes, no en el DOM. Cada elemento personalizado es una aplicación Svelte aislada.

Solución: Usa comunicación basada en el DOM en su lugar:

<!-- 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: Los Métodos del Componente No Están Disponibles Inmediatamente

Problema: Llamar métodos en un elemento personalizado justo después de crearlo falla.

Causa: El componente Svelte interno no se crea hasta el siguiente tick después de connectedCallback.

Solución 1: Espera a que el componente se monte:

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!

Solución 2: Usa la opción extend para métodos siempre disponibles:

<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])
				}
			}
	}}
/>

Mejores Prácticas

1. Siempre Usa `bubbles` y `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. Usa Prefijos en los Nombres de Eventos Personalizados

Evita conflictos con los eventos nativos del 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. Documenta la API de Tu Custom Element

Crea un contrato claro para los 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. Usa CSS Custom Properties para Tematización

Permite que los consumidores personalicen la apariencia sin romper la encapsulación:

<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. Maneja la Limpieza Correctamente

Al usar $host con event listeners u 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. Haz Componentes con Mejora Progresiva

Diseña componentes que funcionen incluso antes de que cargue JavaScript:

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

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

Configuración 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 Asociado a Formulario

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

Conclusiones Clave

La runa $host desbloquea todo el poder de los custom elements en Svelte:

$host() devuelve el elemento host — Acceso directo al nodo del DOM para las APIs web estándar.
Despacha eventos DOM reales — Usa CustomEvent con bubbles y composed para una propagación de eventos adecuada.
Integración con formularios mediante ElementInternals — Crea elementos de formulario personalizados que participan completamente en los formularios HTML.
Accede a propiedades y atributos del host — Lee, escribe y observa cambios en los atributos del custom element.
Encapsulación con Shadow DOM — Los estilos y el DOM están encapsulados por defecto, con CSS custom properties para tematización.
Salida agnóstica al framework — Tus componentes Svelte se convierten en web components estándar utilizables en cualquier lugar.

Los custom elements son una forma poderosa de crear componentes reutilizables y encapsulados que funcionan en distintos frameworks y en HTML plano. Con el soporte de $host y custom elements de Svelte, puedes crear componentes que:

Son agnósticos al framework y pueden usarse en cualquier entorno web
Tienen estilos y comportamiento encapsulados con Shadow DOM
Se integran perfectamente con formularios HTML usando ElementInternals
Ofrecen una excelente experiencia de desarrollo con la reactividad y compilación de Svelte
Pueden publicarse como paquetes independientes en npm o usarse directamente en el navegador
Los custom elements con Shadow DOM tienen estilos aislados, lo que evita conflictos de CSS y reduce los costos de recálculo de estilos

Los custom elements son perfectos para sistemas de diseño, widgets embebibles y cualquier componente que necesite funcionar en diferentes frameworks o en HTML plano. Con $host y la excelente compilación de Svelte, obtienes lo mejor de ambos mundos: una gran experiencia de desarrollo y componentes verdaderamente portables.