Componentes que Funcionan como un Sistema

Algunos patrones de UI requieren múltiples componentes que trabajen juntos como un sistema unificado. Una interfaz de pestañas necesita un contenedor que rastree la pestaña activa, botones de activación que cambien de pestaña y paneles de contenido que se muestren u oculten según la selección. Estos componentes relacionados deben comunicarse internamente mientras presentan una API limpia a los desarrolladores que los usan.

Este patrón se llama componentes compuestos. Los componentes están diseñados para trabajar juntos, compartiendo estado a través del contexto en lugar de props. Desde afuera, los desarrolladores los componen de forma flexible. Por dentro, el contexto coordina su comportamiento.

Considera cómo podrías querer usar un componente de pestañas:

<Tabs>
	<TabList>
		<Tab id="overview">Overview</Tab>
		<Tab id="features">Features</Tab>
		<Tab id="pricing">Pricing</Tab>
	</TabList>

	<TabPanel id="overview">
		<p>Welcome to our product!</p>
	</TabPanel>

	<TabPanel id="features">
		<p>Here are the amazing features...</p>
	</TabPanel>

	<TabPanel id="pricing">
		<p>Choose a plan that works for you.</p>
	</TabPanel>
</Tabs>

Esta API declarativa es intuitiva. Los desarrolladores no necesitan configurar la gestión de estado ni pasar callbacks entre componentes. Simplemente componen las piezas, y el contexto se encarga de la coordinación.

En este artículo, construirás dos sistemas de componentes compuestos: una interfaz de pestañas completamente accesible y un acordeón. Aprenderás los patrones que hacen funcionar a los componentes compuestos y cómo aplicarlos a tus propios diseños.

Entendiendo los Componentes Compuestos

Antes de construir, entendamos qué hace diferentes a los componentes compuestos de los componentes regulares.

El Problema que Resuelven

Imagina construir un componente de pestañas como un único componente monolítico:

<!-- Monolithic approach - limited flexibility -->
<Tabs
	tabs={[
		{ id: 'a', label: 'Tab A', content: 'Content for A' },
		{ id: 'b', label: 'Tab B', content: 'Content for B' }
	]}
/>

Esto funciona para casos simples, pero rápidamente llega a sus límites:

¿Qué pasa si el contenido de las pestañas necesita ser componentes complejos, no solo strings?
¿Qué pasa si quieres íconos en las etiquetas de las pestañas?
¿Qué pasa si necesitas la lista de pestañas y los paneles en diferentes ubicaciones del DOM?
¿Qué pasa si quieres renderizar condicionalmente ciertas pestañas?

El enfoque monolítico obliga a que todo pase a través de props, lo que hace que la personalización sea complicada.

La Solución de los Componentes Compuestos

Los componentes compuestos invierten esto. En lugar de que un componente haga todo, tienes múltiples componentes que cada uno se encarga de una responsabilidad:

Componente	Responsabilidad
`Tabs`	Contenedor que provee contexto y gestiona el estado
`TabList`	Envoltorio para los activadores de pestañas con rol ARIA apropiado
`Tab`	Botón activador de pestaña individual
`TabPanel`	Panel de contenido que se muestra cuando su pestaña está activa

Cada componente es simple. Juntos, crean un sistema flexible.

Cómo el Contexto Hace Posible Esto

La magia está en el contexto. El contenedor Tabs crea un contexto con:

El ID de la pestaña actualmente activa
Una función para cambiar la pestaña activa
Una forma para que las pestañas y los paneles se registren a sí mismos

Los componentes hijos consumen este contexto para:

Saber si deben estar activos (paneles)
Manejar eventos de clic para cambiar de pestaña (activadores de pestañas)
Registrarse a sí mismos para que el sistema sepa qué pestañas existen

No es necesario que los props fluyan a través de componentes intermedios. Un TabPanel en lo profundo del árbol puede acceder directamente al contexto de las pestañas.

Construyendo el Sistema de Pestañas

Construyamos una implementación de pestañas completa y accesible. Aquí hay una descripción general de los componentes:

Componente	Responsabilidad
Context	Estado compartido y métodos para la coordinación de pestañas
`Tabs`	Contenedor que provee contexto y gestiona el estado
`TabList`	Envoltorio para los activadores de pestañas con rol ARIA apropiado
`Tab`	Botón activador de pestaña individual
`TabPanel`	Panel de contenido que se muestra cuando su pestaña está activa

Contexto de Pestañas

Primero, define el contexto que coordina todos los componentes de pestañas:

// src/lib/components/tabs/tabs-context.svelte.ts

import { getContext, hasContext, setContext } from 'svelte'
// Use SvelteKit's `dev` flag to emit helpful warnings during development.
import { dev } from '$app/environment'

/**
 * Symbol key ensures no collisions with other contexts.
 */
const TABS_KEY = Symbol('tabs')

/**
 * The shape of the tabs context available to child components.
 */
export interface TabsContext {
	/** The ID of the currently active tab */
	readonly activeTabId: string

	/** Orientation affects keyboard navigation */
	readonly orientation: 'horizontal' | 'vertical'

	/** Register a tab (called when Tab mounts) */
	registerTab(id: string): void

	/** Unregister a tab (called when Tab unmounts) */
	unregisterTab(id: string): void

	/** Change the active tab */
	setActiveTab(id: string): void

	/** Check if a specific tab is active */
	isActive(id: string): boolean

	/** Get all registered tab IDs in order */
	readonly tabIds: readonly string[]
}

/**
 * Options for creating the tabs context.
 */
export interface TabsOptions {
	/** Initially active tab ID */
	defaultTab?: string

	/** Tab orientation for styling and keyboard nav */
	orientation?: 'horizontal' | 'vertical'

	/** Callback when active tab changes */
	onTabChange?: (tabId: string) => void
}

/**
 * Creates and provides the tabs context.
 * Call this in the Tabs container component.
 */
export function createTabsContext(options: TabsOptions = {}): TabsContext {
	const { defaultTab, onTabChange } = options

	// Orientation derives from the parent option; no local setter to avoid effect loops
	const orientation = $derived(options.orientation ?? 'horizontal')

	// Track registered tabs in order
	let tabIds = $state<string[]>([])

	// Currently active tab
	let activeTabId = $state(defaultTab ?? '')

	// Initial active tab will be set on first register if none is selected

	const context: TabsContext = {
		get activeTabId() {
			return activeTabId
		},

		get orientation() {
			return orientation
		},

		get tabIds() {
			return tabIds
		},

		registerTab(id: string) {
			// Dev-only guard: avoid registering duplicate tab ids (helps catch mistakes)
			if (tabIds.includes(id)) {
				if (dev) console.warn(`[Tabs] Duplicate tab id "${id}" ignored.`)
				return
			}
			// Add to the end, preserving DOM order
			tabIds = [...tabIds, id]
			// If no active tab yet, select the first registered
			if (!activeTabId) {
				activeTabId = id
			}
		},

		unregisterTab(id: string) {
			tabIds = tabIds.filter((tabId) => tabId !== id)

			// If the active tab was removed, select the first available
			if (activeTabId === id && tabIds.length > 0) {
				activeTabId = tabIds[0]
			}
		},

		setActiveTab(id: string) {
			if (tabIds.includes(id) && id !== activeTabId) {
				activeTabId = id
				onTabChange?.(id)
			}
		},

		isActive(id: string) {
			return activeTabId === id
		}

		// orientation is derived from parent option; no local update method
	}

	return setContext(TABS_KEY, context)
}

/**
 * Retrieves the tabs context.
 * Must be called from a component inside Tabs.
 */
export function getTabsContext(): TabsContext {
	if (!hasContext(TABS_KEY)) {
		throw new Error(
			'Tabs context not found. ' + 'Ensure this component is inside a <Tabs> container.'
		)
	}
	return getContext(TABS_KEY)
}

Este contexto provee todo el estado compartido y los métodos necesarios para la coordinación de pestañas.

El Contenedor de Pestañas

A continuación, crea el componente principal Tabs que provee el contexto.

El componente Tabs acepta estas props:

Prop	Descripción
`defaultTab`	ID de la pestaña inicialmente activa
`orientation`	Orientación de las pestañas
`onTabChange`	Callback -fn- cuando cambia la pestaña activa
`class`	Clase CSS adicional
`children`	Contenido hijo

<!-- src/lib/components/tabs/Tabs.svelte -->
<script lang="ts">
	import type { Snippet } from 'svelte'
	import { createTabsContext } from './tabs-context.svelte'

	interface Props {
		/** ID of the initially active tab */
		defaultTab?: string

		/** Tab orientation */
		orientation?: 'horizontal' | 'vertical'

		/** Callback when active tab changes */
		onTabChange?: (tabId: string) => void

		/** Additional CSS class */
		class?: string

		/** Child content */
		children: Snippet
	}

	let {
		defaultTab,
		orientation = 'horizontal',
		onTabChange,
		class: className = '',
		children
	}: Props = $props()

	// Create and provide the context synchronously so children
	// can access it during initial render (important for SSR)
	createTabsContext({
		get defaultTab() {
			return defaultTab
		},
		get orientation() {
			return orientation
		},
		onTabChange: (tabId: string) => onTabChange?.(tabId)
	})
</script>

<div class="tabs tabs-{orientation} {className}" data-orientation={orientation}>
	{@render children()}
</div>

<style>
	.tabs {
		display: flex;
		flex-direction: column;
	}

	.tabs-vertical {
		flex-direction: row;
	}
</style>

La Lista de Pestañas

Ahora crea el componente TabList que envuelve los activadores de pestañas.

El componente TabList acepta estas props:

Prop	Descripción
`class`	Clase CSS adicional
`children`	Botones activadores de pestañas

<!-- src/lib/components/tabs/TabList.svelte -->
<script lang="ts">
	import { getTabsContext } from './tabs-context.svelte'
	import type { Snippet } from 'svelte'

	interface Props {
		/** Additional CSS class */
		class?: string

		/** Tab trigger buttons */
		children: Snippet
	}

	let { class: className = '', children }: Props = $props()

	const tabs = getTabsContext()

	/**
	 * Handles keyboard navigation within the tab list.
	 * Arrow keys move focus between tabs.
	 * Home/End jump to first/last tab.
	 */
	function handleKeyDown(event: KeyboardEvent) {
		const currentIndex = tabs.tabIds.indexOf(tabs.activeTabId)
		if (currentIndex === -1) return

		let newIndex: number | null = null

		// Determine which keys to use based on orientation
		const isHorizontal = tabs.orientation === 'horizontal'
		const prevKey = isHorizontal ? 'ArrowLeft' : 'ArrowUp'
		const nextKey = isHorizontal ? 'ArrowRight' : 'ArrowDown'

		switch (event.key) {
			case prevKey:
				// Move to previous tab, wrap to end
				newIndex = currentIndex > 0 ? currentIndex - 1 : tabs.tabIds.length - 1
				break

			case nextKey:
				// Move to next tab, wrap to start
				newIndex = currentIndex < tabs.tabIds.length - 1 ? currentIndex + 1 : 0
				break

			case 'Home':
				newIndex = 0
				break

			case 'End':
				newIndex = tabs.tabIds.length - 1
				break

			default:
				return // Don't prevent default for other keys
		}

		if (newIndex !== null) {
			event.preventDefault()
			const newTabId = tabs.tabIds[newIndex]
			tabs.setActiveTab(newTabId)

			// Focus the newly active tab button
			const tabButton = document.getElementById(`tab-${newTabId}`)
			tabButton?.focus()
		}
	}
</script>

<div
	class="tab-list {className}"
	role="tablist"
	aria-orientation={tabs.orientation}
	onkeydown={handleKeyDown}
	tabindex="-1"
>
	{@render children()}
</div>

<style>
	.tab-list {
		display: flex;
		gap: 0.25rem;
		border-bottom: 1px solid var(--color-border, #e2e8f0);
	}

	:global([data-orientation='vertical']) .tab-list {
		flex-direction: column;
		border-bottom: none;
		border-right: 1px solid var(--color-border, #e2e8f0);
	}
</style>

El Activador de Pestaña

El siguiente componente es el botón de pestaña individual que los usuarios hacen clic para cambiar de pestaña.

El componente Tab acepta estas props:

Prop	Descripción
`id`	Identificador único para esta pestaña
`disabled`	Si esta pestaña está deshabilitada
`class`	Clase CSS adicional
`children`	Contenido de la etiqueta de la pestaña

<!-- src/lib/components/tabs/Tab.svelte -->
<script lang="ts">
	import { onMount, type Snippet } from 'svelte'
	import { getTabsContext } from './tabs-context.svelte'

	interface Props {
		/** Unique identifier for this tab */
		id: string

		/** Whether this tab is disabled */
		disabled?: boolean

		/** Additional CSS class */
		class?: string

		/** Tab label content */
		children: Snippet
	}

	let { id, disabled = false, class: className = '', children }: Props = $props()

	const tabs = getTabsContext()

	// Track previous id to support controlled re-registration
	let prevId: string | null = null

	// Register this tab on mount, unregister on unmount
	onMount(() => {
		tabs.registerTab(id)
		prevId = id

		return () => {
			// Unregister the latest known id
			tabs.unregisterTab(prevId ?? id)
		}
	})

	// If `id` changes at runtime, re-register under the new id
	// This is useful when:
	// 1. Localization: tab id mirrors a translated slug and can change with language.
	// 2. Data-driven tabs: API results rename or replace identifiers at runtime.
	// 3. Reordering/virtualization: recycled components get new ids as lists change.
	// 4. A/B variants: switching tab definitions without remounting the container.

	$effect(() => {
		if (prevId !== null && id !== prevId) {
			// Guard against id collisions: if new id already exists, keep prevId
			if (tabs.tabIds.includes(id)) {
				console.warn(`[Tabs] Duplicate tab id detected: "${id}". Keeping previous id: "${prevId}"`)
				return
			}
			const wasActive = tabs.activeTabId === prevId
			tabs.unregisterTab(prevId)
			tabs.registerTab(id)
			if (wasActive) {
				tabs.setActiveTab(id)
			}
			prevId = id
		}
	})

	// Reactive check for active state
	let isActive = $derived(tabs.isActive(id))

	/**
	 * Handle tab selection on click.
	 */
	function handleClick() {
		if (!disabled) {
			tabs.setActiveTab(id)
		}
	}
</script>

<button
	type="button"
	id="tab-{id}"
	class="tab {className}"
	class:active={isActive}
	role="tab"
	aria-selected={isActive}
	aria-controls="tabpanel-{id}"
	tabindex={isActive ? 0 : -1}
	{disabled}
	onclick={handleClick}
>
	{@render children()}
</button>

<style>
	.tab {
		padding: 0.75rem 1rem;
		font-size: 0.9375rem;
		font-weight: 500;
		color: var(--color-foreground-muted, #64748b);
		background: transparent;
		border: none;
		border-bottom: 2px solid transparent;
		margin-bottom: -1px;
		cursor: pointer;
		transition:
			color 0.2s,
			border-color 0.2s;
		white-space: nowrap;
	}

	.tab:hover:not(:disabled) {
		color: var(--color-foreground, #1e293b);
	}

	.tab:focus-visible {
		outline: 2px solid var(--color-primary, #3b82f6);
		outline-offset: -2px;
		border-radius: 4px 4px 0 0;
	}

	.tab.active {
		color: var(--color-primary, #3b82f6);
		border-bottom-color: var(--color-primary, #3b82f6);
	}

	.tab:disabled {
		opacity: 0.5;
		cursor: not-allowed;
	}

	/* Vertical orientation styles */
	:global([data-orientation='vertical']) .tab {
		border-bottom: none;
		border-right: 2px solid transparent;
		margin-bottom: 0;
		margin-right: -1px;
		text-align: left;
	}

	:global([data-orientation='vertical']) .tab.active {
		border-right-color: var(--color-primary, #3b82f6);
	}

	:global([data-orientation='vertical']) .tab:focus-visible {
		border-radius: 4px 0 0 4px;
	}
</style>

El TabPanel

Otro componente clave es el panel de contenido que se muestra cuando su pestaña está activa.

El componente TabPanel acepta estas props:

Prop	Descripción
`id`	ID que coincide con el `Tab` asociado
`class`	Clase CSS adicional
`children`	Contenido del panel

<!-- src/lib/components/tabs/TabPanel.svelte -->
<script lang="ts">
	import type { Snippet } from 'svelte'
	import { getTabsContext } from './tabs-context.svelte'

	interface Props {
		/** ID matching the associated Tab */
		id: string

		/** Additional CSS class */
		class?: string

		/** Panel content */
		children: Snippet
	}

	let { id, class: className = '', children }: Props = $props()

	const tabs = getTabsContext()

	// Only render when this panel's tab is active
	let isActive = $derived(tabs.activeTabId === id)
</script>

{#if isActive}
	<div
		id="tabpanel-{id}"
		class="tab-panel {className}"
		role="tabpanel"
		aria-labelledby="tab-{id}"
		tabindex="0"
	>
		{@render children()}
	</div>
{/if}

<style>
	.tab-panel {
		padding: 1.5rem 0;
	}

	.tab-panel:focus-visible {
		outline: 2px solid var(--color-primary, #3b82f6);
		outline-offset: 2px;
		border-radius: 4px;
	}
</style>

Exportando los Componentes

Finalmente, exporta todos los componentes y el contexto desde un único punto de entrada para proporcionar una API pública limpia y fácil de usar para importar y utilizar el sistema de pestañas:

// src/lib/components/tabs/index.ts

export { default as Tabs } from './Tabs.svelte'
export { default as TabList } from './TabList.svelte'
export { default as Tab } from './Tab.svelte'
export { default as TabPanel } from './TabPanel.svelte'

export { getTabsContext } from './tabs-context.svelte'
export type { TabsContext, TabsOptions } from './tabs-context.svelte'

Usando las Pestañas

Ahora los desarrolladores pueden componer pestañas de forma natural usando los componentes exportados y sus características, como en este ejemplo.

<script>
	import { Tabs, TabList, Tab, TabPanel } from '$lib/components/tabs'

	function handleTabChange(tabId: string) {
		console.log('Active tab:', tabId)
	}
</script>

<Tabs defaultTab="features" onTabChange={handleTabChange}>
	<TabList>
		<Tab id="overview">Overview</Tab>
		<Tab id="features">Features</Tab>
		<Tab id="pricing">Pricing</Tab>
		<Tab id="faq" disabled>FAQ (Coming Soon)</Tab>
	</TabList>

	<TabPanel id="overview">
		<h3>Product Overview</h3>
		<p>Welcome to our amazing product. Here's what you need to know...</p>
	</TabPanel>

	<TabPanel id="features">
		<h3>Key Features</h3>
		<ul>
			<li>Feature one with detailed explanation</li>
			<li>Feature two that makes life easier</li>
			<li>Feature three for power users</li>
		</ul>
	</TabPanel>

	<TabPanel id="pricing">
		<h3>Pricing Plans</h3>
		<p>Choose the plan that fits your needs.</p>
	</TabPanel>

	<TabPanel id="faq">
		<h3>Frequently Asked Questions</h3>
		<p>Coming soon!</p>
	</TabPanel>
</Tabs>

Construyendo un Acordeón

El acordeón sigue el mismo patrón de componentes compuestos. Múltiples secciones pueden expandirse o colapsarse, con un comportamiento opcional de un solo elemento abierto a la vez.

Componente	Responsabilidad
Context	Estado compartido y métodos para el control del acordeón
`Accordion`	Contenedor que provee contexto y gestiona el estado
`AccordionItem`	Sección individual expandible/colapsable
`AccordionTrigger`	Botón para alternar la expansión de un elemento
`AccordionContent`	Área de contenido que se muestra cuando el elemento está expandido

Contexto del Acordeón

Primero, define el contexto del acordeón para gestionar el estado de expansión.

// src/lib/components/accordion/accordion-context.svelte.ts

import { getContext, hasContext, setContext } from 'svelte'
import { SvelteSet } from 'svelte/reactivity'
import type { AccordionContext, AccordionOptions } from './types'

const ACCORDION_KEY = Symbol('accordion')

/**
 * Creates and provides the accordion context.
 */
export function createAccordionContext(options: AccordionOptions = {}): AccordionContext {
	const { defaultExpanded = [] } = options
	let { single = false, onExpandedChange } = options

	// Track which items are expanded (keep a single reactive instance)
	const expandedIds = new SvelteSet<string>(defaultExpanded)

	/**
	 * Notifies the callback when expanded items change.
	 */
	function notifyChange() {
		onExpandedChange?.([...expandedIds])
	}

	const context: AccordionContext = {
		get expandedIds() {
			return expandedIds
		},

		get single() {
			return single
		},

		toggle(id: string) {
			if (expandedIds.has(id)) {
				this.collapse(id)
			} else {
				this.expand(id)
			}
		},

		isExpanded(id: string) {
			return expandedIds.has(id)
		},

		expand(id: string) {
			if (single) {
				// In single mode, close others when opening one
				expandedIds.clear()
				expandedIds.add(id)
			} else {
				expandedIds.add(id)
			}
			notifyChange()
		},

		collapse(id: string) {
			expandedIds.delete(id)
			notifyChange()
		},

		collapseAll() {
			expandedIds.clear()
			notifyChange()
		},

		setSingle(value: boolean) {
			single = value
		},

		setOnExpandedChange(cb: ((expandedIds: string[]) => void) | undefined) {
			onExpandedChange = cb
		}
	}

	return setContext(ACCORDION_KEY, context)
}

/**
 * Retrieves the accordion context.
 */
export function getAccordionContext(): AccordionContext {
	if (!hasContext(ACCORDION_KEY)) {
		throw new Error(
			'Accordion context not found. ' + 'Ensure this component is inside an <Accordion> container.'
		)
	}
	return getContext(ACCORDION_KEY)
}

Tipos de Acordeón

// src/lib/components/accordion/types.ts
// The shape of the accordion context.

/**
 * Options for creating the accordion context.
 */
export interface AccordionOptions {
	single?: boolean
	defaultExpanded?: string[]
	onExpandedChange?: (expandedIds: string[]) => void
}

/**
 * The shape of the accordion context.
 */
export interface AccordionContext {
	/** Set of currently expanded item IDs */
	readonly expandedIds: ReadonlySet<string>

	/** Whether only one item can be open at a time */
	readonly single: boolean

	/** Toggle an item's expanded state */
	toggle(id: string): void

	/** Check if an item is expanded */
	isExpanded(id: string): boolean

	/** Expand a specific item */
	expand(id: string): void

	/** Collapse a specific item */
	collapse(id: string): void

	/** Collapse all items */
	collapseAll(): void

	/** Update whether only one item can be open */
	setSingle(value: boolean): void

	/** Update expanded-change callback */
	setOnExpandedChange(cb: ((expandedIds: string[]) => void) | undefined): void
}

/**
 * Options for creating the accordion context.
 */
export interface AccordionOptions {
	/** Allow only one item open at a time */
	single?: boolean

	/** Initially expanded item IDs */
	defaultExpanded?: string[]

	/** Callback when expanded items change */
	onExpandedChange?: (expandedIds: string[]) => void
}

El Contenedor del Acordeón

Este componente provee el contexto del acordeón y gestiona el comportamiento general.

Prop	Descripción
`single`	Solo permite que un elemento esté abierto a la vez
`defaultExpanded`	IDs de elementos inicialmente expandidos
`onExpandedChange`	Callback -fn- cuando cambian los elementos expandidos
`class`	Clase CSS adicional
`children`	Contenido hijo

<!-- src/lib/components/accordion/Accordion.svelte -->
<script lang="ts">
	import type { Snippet } from 'svelte'
	import { createAccordionContext } from './accordion-context.svelte'

	interface Props {
		/** Only allow one item open at a time */
		single?: boolean

		/** Initially expanded item IDs */
		defaultExpanded?: string[]

		/** Callback when expanded items change */
		onExpandedChange?: (expandedIds: string[]) => void

		/** Additional CSS class */
		class?: string

		/** Child content */
		children: Snippet
	}

	let {
		single = false,
		defaultExpanded = [],
		onExpandedChange,
		class: className = '',
		children
	}: Props = $props()

	// Keep a reference to the context so we can react to prop changes
	const accordion = createAccordionContext({})

	// Enforce single-mode dynamically if `single` changes
	$effect(() => {
		// keep the change callback up to date
		accordion.setOnExpandedChange(onExpandedChange)
		// keep context's single in sync
		accordion.setSingle(single)
		if (single) {
			// If more than one is open, collapse extras
			let keep: string | undefined
			for (const id of accordion.expandedIds) {
				keep = id
				break
			}
			for (const id of accordion.expandedIds) {
				if (keep && id !== keep) {
					accordion.collapse(id)
				}
			}
		}
	})

	// Reflect `defaultExpanded` updates by resetting expanded items
	$effect(() => {
		accordion.collapseAll()
		for (const id of defaultExpanded) {
			accordion.expand(id)
		}
	})
</script>

<div class="accordion {className}">
	{@render children()}
</div>

<style>
	.accordion {
		display: flex;
		flex-direction: column;
		border: 1px solid var(--color-border, #e2e8f0);
		border-radius: 8px;
		overflow: hidden;
	}
</style>

El Elemento del Acordeón

Este componente representa una sección individual expandible/colapsable dentro del acordeón.

Prop	Descripción
`id`	Identificador único para este elemento
`class`	Clase CSS adicional
`children`	Contenido del elemento (debe contener `AccordionTrigger` y `AccordionContent`)

<!-- src/lib/components/accordion/AccordionItem.svelte -->
<script lang="ts">
	import { getAccordionContext } from './accordion-context.svelte'
	import type { Snippet } from 'svelte'

	interface Props {
		/** Unique identifier for this item */
		id: string

		/** Additional CSS class */
		class?: string

		/** Item content (should contain AccordionTrigger and AccordionContent) */
		children: Snippet
	}

	let { id, class: className = '', children }: Props = $props()

	const accordion = getAccordionContext()

	let isExpanded = $derived(accordion.isExpanded(id))
</script>

<div
	class="accordion-item {className}"
	class:expanded={isExpanded}
	data-state={isExpanded ? 'open' : 'closed'}
>
	{@render children()}
</div>

<style>
	.accordion-item {
		border-bottom: 1px solid var(--color-border, #e2e8f0);
	}

	.accordion-item:last-child {
		border-bottom: none;
	}
</style>

El Activador del Acordeón

Este componente actúa como el botón para alternar la expansión de un elemento del acordeón.

Prop	Descripción
`itemId`	ID del elemento del acordeón
`class`	Clase CSS adicional
`children`	Contenido de la etiqueta del activador

<!-- src/lib/components/accordion/AccordionTrigger.svelte -->
<script lang="ts">
	import { getAccordionContext } from './accordion-context.svelte'
	import type { Snippet } from 'svelte'

	interface Props {
		/** ID of the accordion item this trigger controls */
		itemId: string

		/** Additional CSS class */
		class?: string

		/** Trigger label content */
		children: Snippet
	}

	let { itemId, class: className = '', children }: Props = $props()

	const accordion = getAccordionContext()

	let isExpanded = $derived(accordion.isExpanded(itemId))

	function handleClick() {
		accordion.toggle(itemId)
	}

	function handleKeyDown(event: KeyboardEvent) {
		if (event.key === 'Enter' || event.key === ' ') {
			event.preventDefault()
			accordion.toggle(itemId)
		}
	}
</script>

<button
	type="button"
	id="accordion-trigger-{itemId}"
	class="accordion-trigger {className}"
	aria-expanded={isExpanded}
	aria-controls="accordion-content-{itemId}"
	onclick={handleClick}
	onkeydown={handleKeyDown}
>
	<span class="trigger-text">
		{@render children()}
	</span>

	<svg
		class="trigger-icon"
		class:rotated={isExpanded}
		viewBox="0 0 24 24"
		fill="none"
		stroke="currentColor"
		stroke-width="2"
		aria-hidden="true"
	>
		<polyline points="6 9 12 15 18 9" />
	</svg>
</button>

<style>
	.accordion-trigger {
		display: flex;
		align-items: center;
		justify-content: space-between;
		width: 100%;
		padding: 1rem 1.25rem;
		font-size: 0.9375rem;
		font-weight: 500;
		text-align: left;
		color: var(--color-foreground, #1e293b);
		background: transparent;
		border: none;
		cursor: pointer;
		transition: background-color 0.2s;
	}

	.accordion-trigger:hover {
		background-color: var(--color-surface, #f8fafc);
	}

	.accordion-trigger:focus-visible {
		outline: 2px solid var(--color-primary, #3b82f6);
		outline-offset: -2px;
	}

	.trigger-text {
		flex: 1;
	}

	.trigger-icon {
		width: 20px;
		height: 20px;
		color: var(--color-foreground-muted, #64748b);
		transition: transform 0.2s ease;
		flex-shrink: 0;
	}

	.trigger-icon.rotated {
		transform: rotate(180deg);
	}
</style>

El Contenido del Acordeón

Este componente muestra el contenido de cada elemento del acordeón cuando está expandido.

Prop	Descripción
`itemId`	ID del elemento del acordeón
`class`	Clase CSS adicional
`children`	Contenido a mostrar cuando está expandido

<!-- src/lib/components/accordion/AccordionContent.svelte -->
<script lang="ts">
	import { getAccordionContext } from './accordion-context.svelte'
	import type { Snippet } from 'svelte'

	interface Props {
		/** ID of the accordion item this content belongs to */
		itemId: string

		/** Additional CSS class */
		class?: string

		/** Content to show when expanded */
		children: Snippet
	}

	let { itemId, class: className = '', children }: Props = $props()

	const accordion = getAccordionContext()

	let isExpanded = $derived(accordion.isExpanded(itemId))
</script>

<div
	id="accordion-content-{itemId}"
	class="accordion-content {className}"
	class:expanded={isExpanded}
	role="region"
	aria-labelledby="accordion-trigger-{itemId}"
	hidden={!isExpanded}
>
	<div class="content-inner">
		{@render children()}
	</div>
</div>

<style>
	.accordion-content {
		display: grid;
		grid-template-rows: 0fr;
		transition: grid-template-rows 0.2s ease;
	}

	.accordion-content.expanded {
		grid-template-rows: 1fr;
	}

	.content-inner {
		overflow: hidden;
	}

	.accordion-content.expanded .content-inner {
		padding: 0 1.25rem 1rem;
	}
</style>

Exportando los Componentes

Finalmente, exporta todos los componentes del acordeón y el contexto desde un único punto de entrada para proporcionar una API pública limpia y fácil de usar.

// src/lib/components/accordion/index.ts

export { default as Accordion } from './Accordion.svelte'
export { default as AccordionContent } from './AccordionContent.svelte'
export { default as AccordionItem } from './AccordionItem.svelte'
export { default as AccordionTrigger } from './AccordionTrigger.svelte'

export { getAccordionContext } from './accordion-context.svelte'

Usando el Acordeón

<script>
	import {
		Accordion,
		AccordionItem,
		AccordionTrigger,
		AccordionContent
	} from '$lib/components/accordion'
</script>

<!-- Single mode: only one item open at a time -->
<Accordion single defaultExpanded={['item-1']}>
	<AccordionItem id="item-1">
		<AccordionTrigger itemId="item-1">What is your return policy?</AccordionTrigger>
		<AccordionContent itemId="item-1">
			<p>
				We offer a 30-day return policy for all unused items in their original packaging. Simply
				contact our support team to initiate a return.
			</p>
		</AccordionContent>
	</AccordionItem>

	<AccordionItem id="item-2">
		<AccordionTrigger itemId="item-2">How long does shipping take?</AccordionTrigger>
		<AccordionContent itemId="item-2">
			<p>
				Standard shipping takes 5-7 business days. Express shipping is available for 2-3 business
				day delivery.
			</p>
		</AccordionContent>
	</AccordionItem>

	<AccordionItem id="item-3">
		<AccordionTrigger itemId="item-3">Do you ship internationally?</AccordionTrigger>
		<AccordionContent itemId="item-3">
			<p>
				Yes! We ship to over 50 countries. International shipping typically takes 10-14 business
				days.
			</p>
		</AccordionContent>
	</AccordionItem>
</Accordion>

Construyendo un Sistema de Notificaciones Toast

Las pestañas y el acordeón siguen patrones similares: hijos estáticos declarados en el marcado que se registran a sí mismos al montarse. Un sistema de toast introduce conceptos fundamentalmente diferentes: componentes creados dinámicamente en tiempo de ejecución a través de una API imperativa.

Qué hace diferente a Toast

A diferencia de las pestañas donde escribes <Tab id="x"> en tu plantilla, los toasts se crean de forma programática:

<script>
	import { getToastContext } from '$lib/components/toast'

	const toast = getToastContext()

	function handleSave() {
		// After some async operation
		toast.success('Document saved!')
	}
</script>

Esto requiere patrones de contexto diferentes:

Creación imperativa — Funciones que agregan nuevos elementos al estado
Temporizadores de auto-cierre — Limpieza programada después de una duración
Renderizado dinámico — Iteración sobre una colección reactiva
Viewport de posición fija — Los toasts aparecen fuera del flujo normal del documento
Gestión del ciclo de vida de los temporizadores — Limpieza adecuada para prevenir fugas de memoria

Estructura del Proyecto

El sistema de toast consta de seis archivos:

src/lib/components/toast/
├── index.ts                    # Public exports
├── types.ts                    # TypeScript interfaces
├── toast-context.svelte.ts     # Context and state management
├── ToastProvider.svelte        # Provider component
├── ToastViewport.svelte        # Renders toast collection
└── ToastItem.svelte            # Individual toast component

Módulo de Tipos

Primero, define los tipos en un módulo dedicado:

// src/lib/components/toast/types.ts

/**
 * Visual style variants for toast notifications.
 */
export type ToastType = 'info' | 'success' | 'warning' | 'error'

/**
 * Position options for the toast viewport.
 */
export type ToastPosition =
	| 'top-right'
	| 'top-left'
	| 'top-center'
	| 'bottom-right'
	| 'bottom-left'
	| 'bottom-center'

/**
 * A single toast notification instance.
 */
export interface Toast {
	readonly id: string
	readonly message: string
	readonly type: ToastType
	readonly duration: number
	readonly createdAt: number
}

/**
 * Options for creating a new toast.
 */
export interface ToastOptions {
	message: string
	type?: ToastType
	duration?: number
}

/**
 * The public API exposed by the toast context.
 */
export interface ToastContext {
	readonly toasts: readonly Toast[]
	show(options: ToastOptions): string
	dismiss(id: string): void
	dismissAll(): void
	info(message: string, duration?: number): string
	success(message: string, duration?: number): string
	warning(message: string, duration?: number): string
	error(message: string, duration?: number): string
}

/**
 * Configuration for the ToastProvider.
 */
export interface ToastProviderConfig {
	defaultDuration?: number
	maxToasts?: number
	position?: ToastPosition
}

Contexto Toast

El contexto gestiona el estado de los toasts, los temporizadores, y proporciona la API imperativa. Usar una clase encapsula el Map de temporizadores y asegura una limpieza adecuada:

// src/lib/components/toast/toast-context.svelte.ts

import { setContext, getContext, hasContext } from 'svelte'
import type {
	Toast,
	ToastType,
	ToastOptions,
	ToastContext,
	ToastPosition,
	ToastProviderConfig
} from './types.js'

// Re-export types for consumer convenience
export type { Toast, ToastType, ToastOptions, ToastContext, ToastPosition, ToastProviderConfig }

/**
 * Symbol keys for context isolation.
 */
const TOAST_CONTEXT_KEY = Symbol('toast-context')
const TOAST_POSITION_KEY = Symbol('toast-position')

/**
 * Generates a unique ID for each toast.
 */
function generateToastId(): string {
	const timestamp = Date.now().toString(36)
	const random = Math.random().toString(36).substring(2, 9)
	return `toast-${timestamp}-${random}`
}

/**
 * Internal class that manages toast state and timers.
 * Encapsulating in a class ensures the timer Map is properly
 * scoped and avoids closure issues with $state.
 */
class ToastStateManager {
	/** Reactive state for the toasts array */
	private _toasts = $state<Toast[]>([])

	/** Non-reactive Map for tracking auto-dismiss timers */
	private timerRegistry: Map<string, ReturnType<typeof setTimeout>>

	/** Configuration values */
	private readonly defaultDuration: number
	private readonly maxToasts: number

	constructor(defaultDuration: number, maxToasts: number) {
		this.defaultDuration = defaultDuration
		this.maxToasts = maxToasts
		this.timerRegistry = new Map()
	}

	/** Read-only access to toasts */
	get toasts(): readonly Toast[] {
		return this._toasts
	}

	/** Create and show a new toast */
	show(options: ToastOptions): string {
		const toast: Toast = {
			id: generateToastId(),
			message: options.message,
			type: options.type ?? 'info',
			duration: options.duration ?? this.defaultDuration,
			createdAt: Date.now()
		}

		// Add new toast, enforce maxToasts by keeping newest
		this._toasts = [...this._toasts, toast].slice(-this.maxToasts)

		// Schedule auto-dismiss if duration > 0
		if (toast.duration > 0) {
			const timerId = setTimeout(() => {
				this.dismiss(toast.id)
			}, toast.duration)
			this.timerRegistry.set(toast.id, timerId)
		}

		return toast.id
	}

	/** Dismiss a specific toast by ID */
	dismiss(id: string): void {
		// Clear timer first to prevent race conditions
		const timerId = this.timerRegistry.get(id)
		if (timerId !== undefined) {
			clearTimeout(timerId)
			this.timerRegistry.delete(id)
		}

		// Remove from reactive state
		this._toasts = this._toasts.filter((t) => t.id !== id)
	}

	/** Dismiss all toasts and clear all timers */
	dismissAll(): void {
		// Clear all pending timers
		for (const timerId of this.timerRegistry.values()) {
			clearTimeout(timerId)
		}
		this.timerRegistry.clear()

		// Clear toasts array
		this._toasts = []
	}

	/** Cleanup method for when provider unmounts */
	destroy(): void {
		this.dismissAll()
	}
}

/**
 * Creates and provides the toast context.
 * Call this in ToastProvider during component initialization.
 */
export function createToastContext(
	defaultDuration: number,
	maxToasts: number,
	position: ToastPosition
): ToastContext {
	const manager = new ToastStateManager(defaultDuration, maxToasts)

	// Set up cleanup when provider unmounts
	$effect(() => {
		return () => manager.destroy()
	})

	const context: ToastContext = {
		get toasts() {
			return manager.toasts
		},

		show(options: ToastOptions): string {
			return manager.show(options)
		},

		dismiss(id: string): void {
			manager.dismiss(id)
		},

		dismissAll(): void {
			manager.dismissAll()
		},

		// Convenience methods
		info(message: string, duration?: number): string {
			return manager.show({ message, type: 'info', duration })
		},

		success(message: string, duration?: number): string {
			return manager.show({ message, type: 'success', duration })
		},

		warning(message: string, duration?: number): string {
			return manager.show({ message, type: 'warning', duration })
		},

		error(message: string, duration?: number): string {
			return manager.show({ message, type: 'error', duration })
		}
	}

	// Store position in separate context for viewport
	setContext(TOAST_POSITION_KEY, position)

	// Store and return main context
	return setContext(TOAST_CONTEXT_KEY, context)
}

/**
 * Retrieves the toast context.
 * Must be called from a component inside ToastProvider.
 */
export function getToastContext(): ToastContext {
	if (!hasContext(TOAST_CONTEXT_KEY)) {
		throw new Error(
			'Toast context not found. ' + 'Ensure this component is inside a <ToastProvider>.'
		)
	}
	return getContext<ToastContext>(TOAST_CONTEXT_KEY)
}

/**
 * Retrieves the toast position configuration.
 * Used internally by ToastViewport.
 */
export function getToastPosition(): ToastPosition {
	if (!hasContext(TOAST_POSITION_KEY)) {
		return 'bottom-right'
	}
	return getContext<ToastPosition>(TOAST_POSITION_KEY)
}

Componente Proveedor de Toast

El proveedor envuelve tu aplicación y crea el contexto:

<!-- src/lib/components/toast/ToastProvider.svelte -->
<script lang="ts">
	import { createToastContext, type ToastPosition } from './toast-context.svelte.js'
	import type { Snippet } from 'svelte'

	interface Props {
		/** Default toast duration in milliseconds */
		defaultDuration?: number

		/** Maximum visible toasts */
		maxToasts?: number

		/** Viewport position */
		position?: ToastPosition

		/** Child content */
		children: Snippet
	}

	const {
		defaultDuration = 5000,
		maxToasts = 5,
		position = 'bottom-right',
		children
	}: Props = $props()

	// Create context during component initialization.
	// Wrap in `untrack` to intentionally capture initial prop values
	// and avoid state_referenced_locally warnings.
	untrack(() => {
		createToastContext(defaultDuration, maxToasts, position)
	})
</script>

{@render children()}

Componente Viewport de Toast

El viewport renderiza todos los toasts activos en una posición fija:

<!-- src/lib/components/toast/ToastViewport.svelte -->
<script lang="ts">
	import { getToastContext, getToastPosition } from './toast-context.svelte.js'
	import ToastItem from './ToastItem.svelte'

	interface Props {
		/** Additional CSS class */
		class?: string
	}

	let { class: className = '' }: Props = $props()

	const toastCtx = getToastContext()
	const position = getToastPosition()
</script>

<div
	class="toast-viewport {className}"
	data-position={position}
	role="region"
	aria-label="Notifications"
	aria-live="polite"
>
	{#each toastCtx.toasts as toast (toast.id)}
		<ToastItem {toast} ondismiss={() => toastCtx.dismiss(toast.id)} />
	{/each}
</div>

<style>
	.toast-viewport {
		position: fixed;
		z-index: 9999;
		display: flex;
		flex-direction: column;
		gap: 0.5rem;
		padding: 1rem;
		max-width: 420px;
		width: 100%;
		pointer-events: none;
	}

	/* Allow interaction with individual toasts */
	.toast-viewport > :global(*) {
		pointer-events: auto;
	}

	/* Position variants */
	[data-position='top-right'] {
		top: 0;
		right: 0;
	}

	[data-position='top-left'] {
		top: 0;
		left: 0;
	}

	[data-position='top-center'] {
		top: 0;
		left: 50%;
		transform: translateX(-50%);
	}

	[data-position='bottom-right'] {
		bottom: 0;
		right: 0;
		flex-direction: column-reverse;
	}

	[data-position='bottom-left'] {
		bottom: 0;
		left: 0;
		flex-direction: column-reverse;
	}

	[data-position='bottom-center'] {
		bottom: 0;
		left: 50%;
		transform: translateX(-50%);
		flex-direction: column-reverse;
	}
</style>

Componente de Elemento Toast

Toast individual con estilos y botón de descarte:

<!-- src/lib/components/toast/ToastItem.svelte -->
<script lang="ts">
	import type { Toast } from './types.js'

	interface Props {
		/** Toast data */
		toast: Toast

		/** Dismiss callback */
		ondismiss: () => void
	}

	const { toast, ondismiss }: Props = $props()

	// Type-safe icon mapping
	const icons: Record<Toast['type'], string> = {
		info: 'ℹ️',
		success: '✅',
		warning: '⚠️',
		error: '❌'
	}
</script>

<div class="toast toast-{toast.type}" role="alert">
	<span class="toast-icon" aria-hidden="true">
		{icons[toast.type]}
	</span>

	<p class="toast-message">
		{toast.message}
	</p>

	<button type="button" class="toast-dismiss" onclick={ondismiss} aria-label="Dismiss notification">
		<svg
			viewBox="0 0 24 24"
			fill="none"
			stroke="currentColor"
			stroke-width="2"
			stroke-linecap="round"
			stroke-linejoin="round"
			aria-hidden="true"
		>
			<path d="M18 6L6 18M6 6l12 12" />
		</svg>
	</button>
</div>

<style>
	.toast {
		display: flex;
		align-items: flex-start;
		gap: 0.75rem;
		padding: 1rem;
		border-radius: 8px;
		background: var(--toast-bg, #ffffff);
		box-shadow:
			0 4px 12px rgba(0, 0, 0, 0.15),
			0 1px 3px rgba(0, 0, 0, 0.1);
		border-left: 4px solid;
		animation: toast-slide-in 0.3s ease-out;
	}

	@keyframes toast-slide-in {
		from {
			opacity: 0;
			transform: translateX(100%);
		}
		to {
			opacity: 1;
			transform: translateX(0);
		}
	}

	/* Type-specific border colors */
	.toast-info {
		border-color: var(--toast-info, #3b82f6);
	}

	.toast-success {
		border-color: var(--toast-success, #10b981);
	}

	.toast-warning {
		border-color: var(--toast-warning, #f59e0b);
	}

	.toast-error {
		border-color: var(--toast-error, #ef4444);
	}

	.toast-icon {
		flex-shrink: 0;
		font-size: 1.125rem;
		line-height: 1;
	}

	.toast-message {
		flex: 1;
		margin: 0;
		font-size: 0.9375rem;
		line-height: 1.5;
		color: var(--toast-text, #1e293b);
		word-break: break-word;
	}

	.toast-dismiss {
		flex-shrink: 0;
		width: 20px;
		height: 20px;
		padding: 0;
		background: transparent;
		border: none;
		border-radius: 4px;
		cursor: pointer;
		color: var(--toast-dismiss, #64748b);
		transition:
			color 0.15s,
			background-color 0.15s;
	}

	.toast-dismiss:hover {
		color: var(--toast-dismiss-hover, #1e293b);
		background-color: rgba(0, 0, 0, 0.05);
	}

	.toast-dismiss:focus-visible {
		outline: 2px solid var(--toast-focus, #3b82f6);
		outline-offset: 2px;
	}

	.toast-dismiss svg {
		width: 100%;
		height: 100%;
	}
</style>

Exportaciones de la API Pública

El archivo index proporciona una interfaz pública limpia:

// src/lib/components/toast/index.ts

// Components
export { default as ToastProvider } from './ToastProvider.svelte'
export { default as ToastViewport } from './ToastViewport.svelte'
export { default as ToastItem } from './ToastItem.svelte'

// Context accessor
export { getToastContext } from './toast-context.svelte.js'

// Types - re-export from types.ts for consumers
export type {
	Toast,
	ToastType,
	ToastOptions,
	ToastContext,
	ToastPosition,
	ToastProviderConfig
} from './types.js'

Usando el Sistema Toast

Configura el proveedor en tu layout raíz:

<!-- src/routes/+layout.svelte -->
<script lang="ts">
	import { ToastProvider, ToastViewport } from '$lib/components/toast'

	const { children } = $props()
</script>

<ToastProvider position="bottom-right" defaultDuration={5000} maxToasts={5}>
	{@render children()}

	<!-- Viewport renders all toasts -->
	<ToastViewport />
</ToastProvider>

Usa la API de toast en cualquier parte de tu aplicación:

<!-- src/routes/+page.svelte -->
<script lang="ts">
	import { getToastContext } from '$lib/components/toast'

	const toast = getToastContext()

	// Simulated async operation
	async function saveDocument(): Promise<void> {
		return new Promise((resolve) => setTimeout(resolve, 500))
	}

	async function handleSave(): Promise<void> {
		try {
			await saveDocument()
			toast.success('Document saved successfully!')
		} catch {
			toast.error('Failed to save document. Please try again.')
		}
	}

	function showExamples(): void {
		toast.info('This is an informational message')
		toast.success('Operation completed!')
		toast.warning('Your session expires in 5 minutes', 10000)
		toast.error('Something went wrong')
	}

	function showPersistent(): void {
		// Using the full options API
		const id = toast.show({
			message: 'This toast stays until dismissed',
			type: 'info',
			duration: 0 // 0 = no auto-dismiss
		})

		// Programmatic dismiss after 8 seconds
		setTimeout(() => toast.dismiss(id), 8000)
	}
</script>

<div class="demo">
	<h1>Toast Demo</h1>

	<div class="buttons">
		<button type="button" onclick={handleSave}>Save Document</button>
		<button type="button" onclick={showExamples}>Show All Types</button>
		<button type="button" onclick={showPersistent}>Persistent Toast</button>
		<button type="button" onclick={() => toast.dismissAll()}>Dismiss All</button>
	</div>
</div>

<style>
	.demo {
		padding: 2rem;
	}

	.buttons {
		display: flex;
		gap: 1rem;
		flex-wrap: wrap;
	}

	button {
		padding: 0.75rem 1.5rem;
		font-size: 1rem;
		border-radius: 6px;
		border: none;
		background: #3b82f6;
		color: white;
		cursor: pointer;
		transition: background-color 0.15s;
	}

	button:hover {
		background: #2563eb;
	}
</style>

Diferencias Clave con Pestañas/Acordeón

El sistema de toast demuestra patrones de componentes compuestos fundamentalmente diferentes:

Aspecto	Pestañas/Acordeón	Sistema Toast
Hijos	Declarados en el marcado	Creados en tiempo de ejecución via API
Estilo de API	Composición declarativa	Llamadas a funciones imperativas
Ciclo de vida	Montaje/desmontaje con el padre	Auto-cierre temporizado
Renderizado	En línea en el árbol de componentes	Viewport de posición fija
Forma del estado	ID activo / Conjunto de IDs	Array dinámico de objetos
Registro	Los componentes se auto-registran	Elementos agregados via `show()`
Limpieza	Automática al desmontar	Gestión explícita de temporizadores

El patrón toast aplica cuando necesitas crear elementos de UI de forma programática: modales activados por eventos, paletas de comandos, notificaciones dinámicas, o cualquier overlay que no encaja naturalmente en la jerarquía de componentes.

Patrones y Buenas Prácticas

Construir componentes compuestos revela varios patrones importantes.

Registro de Componentes con Effects

Los componentes hijos necesitan registrarse con el contexto padre cuando se montan y desregistrarse cuando se desmontan. En Svelte 5, usa $effect con una función de limpieza:

<script>
	const tabs = getTabsContext()

	// Register on mount, unregister on unmount
	$effect(() => {
		tabs.registerTab(id)

		return () => {
			tabs.unregisterTab(id)
		}
	})
</script>

Este patrón asegura que el padre siempre sepa qué hijos existen, incluso cuando aparecen y desaparecen dinámicamente.

Estado Derivado para Verificaciones Reactivas

En lugar de llamar funciones en la plantilla, deriva estados booleanos:

<script>
  const tabs = getTabsContext()

  // ✅ Good: Derive once, use reactively
  let isActive = $derived(tabs.isActive(id))
</script>

<!-- Clean template usage -->
<button class:active={isActive}>

Este enfoque es más limpio y asegura que el valor se actualice cada vez que cambien las dependencias.

Navegación por Teclado

Los componentes compuestos frecuentemente necesitan soporte de teclado para la accesibilidad. Maneja esto a nivel del contenedor:

<script>
	function handleKeyDown(event: KeyboardEvent) {
		switch (event.key) {
			case 'ArrowRight':
				// Navigate to next item
				break
			case 'ArrowLeft':
				// Navigate to previous item
				break
			case 'Home':
				// Navigate to first item
				break
			case 'End':
				// Navigate to last item
				break
		}
	}
</script>

<div role="tablist" onkeydown={handleKeyDown}>
	{@render children()}
</div>

Atributos ARIA

Los atributos ARIA adecuados hacen que los componentes compuestos sean accesibles:

Pestañas:

Contenedor: role="tablist", aria-orientation
Pestaña: role="tab", aria-selected, aria-controls, tabindex
Panel: role="tabpanel", aria-labelledby

Acordeón:

Disparador: aria-expanded, aria-controls
Contenido: role="region", aria-labelledby, hidden

Enlace por ID

Los componentes se referencian entre sí a través de atributos ID:

<!-- Tab references its panel -->
<button
  id="tab-{id}"
  aria-controls="tabpanel-{id}"
>

<!-- Panel references its tab -->
<div
  id="tabpanel-{id}"
  aria-labelledby="tab-{id}"
>

Esto crea la conexión semántica que las tecnologías de asistencia necesitan.

Cuándo Usar Componentes Compuestos

Los componentes compuestos funcionan bien cuando:

Múltiples componentes trabajan como una unidad — Pestañas, acordeones, menús, selectores desplegables
La flexibilidad en la composición importa — Los usuarios necesitan personalizar la estructura o agregar elementos personalizados
El estado interno debe estar oculto — La complejidad de la gestión del estado permanece dentro del sistema
Se requiere un comportamiento consistente — Todas las pestañas deben funcionar de la misma manera

Considera alternativas más simples cuando:

El componente es independiente — Un botón individual no necesita patrones compuestos
Las props son suficientes — Si una API de props simple cubre todos los casos de uso, no sobre-ingenierices
Los hijos no necesitan coordinación — Si los componentes hijos no interactúan, el contexto agrega complejidad innecesaria

Consideraciones de Rendimiento

Los componentes compuestos pueden escalar a casos de uso complejos, pero entender sus características de rendimiento te ayuda a construir de manera eficiente.

Costo de Búsqueda en Contexto

Cada componente hijo llama a getContext una vez durante la inicialización. Para componentes compuestos típicos con 5 a 20 hijos, este costo es insignificante. Sin embargo, si estás renderizando cientos de elementos (como una lista virtualizada), considera si el patrón compuesto es apropiado.

<!-- ✅ Good: Reasonable number of tabs -->
<Tabs>
	<TabList>
		{#each categories as cat (cat.id)}
			<Tab id={cat.id}>{cat.name}</Tab>
		{/each}
	</TabList>
	<!-- panels... -->
</Tabs>

<!-- ⚠️ Consider alternatives for hundreds of items -->
<Accordion>
	{#each thousandsOfItems as item (item.id)}
		<AccordionItem id={item.id}>
			<!-- Each item calls getContext -->
		</AccordionItem>
	{/each}
</Accordion>

Para listas grandes, considera la virtualización o un enfoque más simple orientado a datos.

Contenido de Panel Diferido

Por defecto, nuestro TabPanel solo se renderiza cuando está activo. Esto es eficiente — los paneles inactivos no existen en el DOM:

{#if isActive}
	<div class="tab-panel">
		{@render children()}
	</div>
{/if}

Sin embargo, esto significa que el contenido se desmonta al cambiar de pestaña. Si los paneles contienen contenido costoso de inicializar (formularios complejos, visualizaciones pesadas), considera mantenerlos montados pero ocultos:

<!-- Alternative: Keep mounted, toggle visibility -->
<div class="tab-panel" class:hidden={!isActive} hidden={!isActive} inert={!isActive}>
	{@render children()}
</div>

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

El atributo inert evita la interacción por teclado con el contenido oculto.

Sobrecarga de Registro

El patrón de registro (llamar a registerTab en $effect) se ejecuta para cada hijo al montarse. Para listas dinámicas que agregan y eliminan elementos con frecuencia, considera agrupar las operaciones:

// In context, batch registrations
let pendingRegistrations: string[] = []
let registrationTimeout: ReturnType<typeof setTimeout> | null = null

function registerTab(id: string) {
	pendingRegistrations.push(id)

	if (!registrationTimeout) {
		registrationTimeout = setTimeout(() => {
			tabIds = [...tabIds, ...pendingRegistrations]
			pendingRegistrations = []
			registrationTimeout = null
		}, 0)
	}
}

Esto agrupa múltiples registros en una sola actualización de estado. Para la mayoría de los casos de uso, esta optimización no es necesaria — Svelte ya agrupa las actualizaciones síncronas.

Limpieza de Temporizadores de Toast

El sistema de toasts crea temporizadores para el cierre automático. Siempre limpia los temporizadores cuando los toasts se descartan o el proveedor se desmonta:

// In toast context
function dismiss(id: string) {
	clearTimer(id) // Important: Clear timer before removing
	toasts = toasts.filter((t) => t.id !== id)
}

// If provider could unmount, clean up all timers
$effect(() => {
	return () => {
		for (const timer of timers.values()) {
			clearTimeout(timer)
		}
		timers.clear()
	}
})

Los temporizadores sin limpiar pueden causar problemas de memoria y errores si se disparan después del desmontaje.

Conclusión

Los componentes compuestos representan el contexto en su forma más elegante. El patrón resuelve un problema genuino — ¿cómo construyes sistemas de UI flexibles donde múltiples componentes trabajan juntos sin obligar a los desarrolladores a conectar manualmente la gestión de estado? La respuesta es ocultar la coordinación detrás de una API composicional limpia. Los desarrolladores organizan los componentes de forma declarativa, y el contexto se encarga de la comunicación interna.

El patrón de registro es central para que los componentes compuestos funcionen. Cuando un Tab se monta, se registra con el contexto de Tabs. Cuando se desmonta, se desregistra. Esto significa que el padre siempre sabe qué hijos existen, incluso cuando aparecen y desaparecen dinámicamente. El $effect con función de limpieza hace que este patrón sea natural en Svelte 5 — el efecto se ejecuta al montarse para registrar, y su función de limpieza se ejecuta al desmontarse para desregistrar.

Lo que hace que los componentes compuestos sean particularmente valiosos es que mueven la complejidad al lugar correcto. La navegación por teclado, los atributos ARIA, la gestión del foco, la sincronización de estado — todo esto vive dentro del sistema de componentes compuestos, implementado una vez y funcionando para cada uso. Los desarrolladores que usan los componentes no necesitan pensar en estos detalles. Componen las piezas, y la accesibilidad y el comportamiento vienen de forma gratuita. Ese es el objetivo de las buenas abstracciones: ocultar la complejidad mientras se expone la flexibilidad.

Puntos Clave

Los componentes compuestos usan el contexto para crear sistemas de UI flexibles y componibles:

El contexto provee coordinación — El contenedor padre crea un contexto que los hijos consumen. Los hijos se registran, leen el estado compartido y desencadenan acciones a través del contexto.

Los componentes se mantienen enfocados — Cada componente maneja una responsabilidad. El contenedor gestiona el estado, los disparadores manejan la interacción y el contenido se encarga de la visualización.

La composición habilita la flexibilidad — Los desarrolladores organizan los componentes según sea necesario. Pueden agregar elementos personalizados, renderizar piezas condicionalmente o colocar componentes en diferentes estructuras del DOM.

Los patrones de registro rastrean a los hijos — Usando $effect con funciones de limpieza, los hijos se registran al montarse y se desregistran al desmontarse. El padre siempre sabe qué existe.

La accesibilidad viene incorporada — Los atributos ARIA, la navegación por teclado y la gestión del foco se manejan una vez en el sistema de componentes compuestos, beneficiando todos los usos.

Los mismos patrones se aplican a muchos componentes de UI: menús, comboboxes, widgets de divulgación, sistemas de navegación y más. Una vez que entiendes el patrón, puedes aplicarlo en cualquier lugar donde múltiples componentes necesiten trabajar juntos como un sistema coordinado.

¿Qué Sigue?

¡Felicitaciones! Has completado la serie sobre la API de Contexto.

Ahora tienes el conocimiento para construir arquitecturas sofisticadas basadas en contexto en Svelte 5. En los siguientes artículos reuniremos todo con ejemplos del mundo real usando patrones de la API de Contexto.

Gestión de temas — Modo claro/oscuro con preferencias del sistema
Carrito de compras — Carrito de e-commerce con funcionalidad de agregar/eliminar
Asistente de formulario de múltiples pasos — Estado de formulario centralizado con validación
Sistema de autenticación — Estado de inicio de sesión del usuario y rutas protegidas
SaaS multi-tenant con API de Contexto — Configuraciones y datos específicos del tenant

Componentes que Funcionan como un Sistema

Entendiendo los Componentes Compuestos

El Problema que Resuelven

La Solución de los Componentes Compuestos

Cómo el Contexto Hace Posible Esto

Construyendo el Sistema de Pestañas

Contexto de Pestañas

El Contenedor de Pestañas

La Lista de Pestañas

El Activador de Pestaña

El TabPanel

Exportando los Componentes

Usando las Pestañas

Construyendo un Acordeón

Contexto del Acordeón

Tipos de Acordeón

El Contenedor del Acordeón

El Elemento del Acordeón

El Activador del Acordeón

El Contenido del Acordeón

Exportando los Componentes

Usando el Acordeón

Construyendo un Sistema de Notificaciones Toast

Qué hace diferente a Toast

Estructura del Proyecto

Módulo de Tipos

Contexto Toast

Componente Proveedor de Toast

Componente Viewport de Toast

Componente de Elemento Toast

Exportaciones de la API Pública

Usando el Sistema Toast

Diferencias Clave con Pestañas/Acordeón

Patrones y Buenas Prácticas

Registro de Componentes con Effects

Estado Derivado para Verificaciones Reactivas

Navegación por Teclado

Atributos ARIA

Enlace por ID

Cuándo Usar Componentes Compuestos

Consideraciones de Rendimiento

Costo de Búsqueda en Contexto

Contenido de Panel Diferido

Sobrecarga de Registro

Limpieza de Temporizadores de Toast

Conclusión

Puntos Clave

¿Qué Sigue?

Ver También

Recursos de Accesibilidad

Artículos Relacionados