Componentes Que Funcionam como um Sistema

Alguns padrões de UI exigem múltiplos componentes que trabalham juntos como um sistema unificado. Uma interface de abas precisa de um contêiner que rastreie a aba ativa, botões de gatilho que alternem as abas e painéis de conteúdo que mostrem ou ocultem com base na seleção. Esses componentes relacionados precisam se comunicar internamente enquanto apresentam uma API limpa para os desenvolvedores que os utilizam.

Esse padrão é chamado de componentes compostos. Os componentes são projetados para trabalhar juntos, compartilhando estado por meio de context em vez de props. Por fora, os desenvolvedores os compõem de forma flexível. Por dentro, o context coordena seu comportamento.

Considere como você poderia querer usar um componente de abas:

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

Essa API declarativa é intuitiva. Os desenvolvedores não precisam configurar o gerenciamento de estado nem passar callbacks entre componentes. Eles simplesmente compõem as peças, e o context cuida da coordenação.

Neste artigo, você construirá dois sistemas de componentes compostos: uma interface de abas totalmente acessível e um acordeão. Você aprenderá os padrões que fazem os componentes compostos funcionarem e como aplicá-los aos seus próprios projetos.

Entendendo Componentes Compostos

Antes de construir, vamos entender o que torna os componentes compostos diferentes dos componentes comuns.

O Problema Que Eles Resolvem

Imagine construir um componente de abas como um ú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' }
	]}
/>

Isso funciona para casos simples, mas rapidamente encontra limitações:

E se o conteúdo das abas precisar ser componentes complexos, não apenas strings?
E se você quiser ícones nos rótulos das abas?
E se você precisar da lista de abas e dos painéis em locais diferentes no DOM?
E se você quiser renderizar condicionalmente certas abas?

A abordagem monolítica força tudo a passar por props, tornando a personalização complicada.

A Solução dos Componentes Compostos

Os componentes compostos invertem isso. Em vez de um único componente fazendo tudo, você tem múltiplos componentes que cada um cuida de uma responsabilidade:

Componente	Responsabilidade
`Tabs`	Contêiner que fornece context e gerencia o estado
`TabList`	Wrapper para os gatilhos de aba com role ARIA adequado
`Tab`	Botão gatilho de aba individual
`TabPanel`	Painel de conteúdo que aparece quando sua aba está ativa

Cada componente é simples. Juntos, eles criam um sistema flexível.

Como o Context Torna Isso Possível

A mágica é o context. O contêiner Tabs cria um context com:

O ID da aba atualmente ativa
Uma função para alterar a aba ativa
Uma forma para abas e painéis se registrarem

Os componentes filhos consomem esse context para:

Saber se devem estar ativos (painéis)
Lidar com eventos de clique para alternar abas (gatilhos de aba)
Registrar-se para que o sistema saiba quais abas existem

Nenhuma prop precisa fluir por componentes intermediários. Um TabPanel em qualquer nível da árvore pode acessar diretamente o context das abas.

Construindo o Sistema de Abas

Vamos construir uma implementação de abas completa e acessível. Aqui está uma visão geral dos componentes:

Componente	Responsabilidade
Context	Estado compartilhado e métodos para coordenação das abas
`Tabs`	Contêiner que fornece context e gerencia o estado
`TabList`	Wrapper para os gatilhos de aba com role ARIA adequado
`Tab`	Botão gatilho de aba individual
`TabPanel`	Painel de conteúdo que aparece quando sua aba está ativa

Context das Abas

Primeiro, defina o context que coordena todos os componentes de aba:

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

Esse context fornece todo o estado compartilhado e os métodos necessários para a coordenação das abas.

O Contêiner Tabs

Em seguida, crie o componente principal Tabs que fornece o context.

O componente Tabs aceita estas props:

Prop	Descrição
`defaultTab`	ID da aba inicialmente ativa
`orientation`	Orientação das abas
`onTabChange`	Callback -fn- quando a aba ativa muda
`class`	Classe CSS adicional
`children`	Conteúdo filho

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

A Lista de Abas

Agora crie o componente TabList que envolve os gatilhos de aba.

O componente TabList aceita estas props:

Prop	Descrição
`class`	classe css adicional
`children`	botões gatilho de aba

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

O Gatilho de Aba

O próximo componente é o botão de aba individual que os usuários clicam para alternar as abas.

O componente Tab aceita estas props:

Prop	Descrição
`id`	identificador único para esta aba
`disabled`	se esta aba está desabilitada
`class`	classe css adicional
`children`	conteúdo do rótulo da aba

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

O TabPanel

Outro componente chave é o painel de conteúdo que aparece quando sua aba está ativa.

O componente TabPanel aceita estas props:

Prop	Descrição
`id`	ID correspondente à Tab associada
`class`	classe css adicional
`children`	conteúdo do painel

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

Por fim, exporte todos os componentes e o context a partir de um único ponto de entrada para fornecer uma API pública limpa e fácil de usar para importar e utilizar o sistema de abas:

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

Agora os desenvolvedores podem compor abas naturalmente usando os componentes exportados e seus recursos, como neste exemplo.

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

Construindo um Acordeão

O acordeão segue o mesmo padrão de componentes compostos. Múltiplas seções podem expandir ou recolher, com comportamento opcional de apenas um item aberto por vez.

Componente	Responsabilidade
Context	Estado compartilhado e métodos para controle do acordeão
`Accordion`	Contêiner que fornece context e gerencia o estado
`AccordionItem`	Seção individual expansível/recolhível
`AccordionTrigger`	Botão para alternar a expansão de um item
`AccordionContent`	Área de conteúdo exibida quando o item está expandido

Context do Acordeão

Primeiro, defina o context do acordeão para gerenciar o estado de expansão.

// 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 do Acordeão

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

O Contêiner Accordion

Este componente fornece o context do acordeão e gerencia o comportamento geral.

Prop	Descrição
`single`	Permitir apenas um item aberto por vez
`defaultExpanded`	IDs dos itens inicialmente expandidos
`onExpandedChange`	Callback -fn- quando os itens expandidos mudam
`class`	Classe CSS adicional
`children`	Conteúdo filho

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

O Item do Acordeão

Este componente representa uma única seção expansível/recolhível dentro do acordeão.

Prop	Descrição
`id`	Identificador único para este item
`class`	classe css adicional
`children`	Conteúdo do item (deve conter AccordionTrigger e 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>

O Gatilho do Acordeão

Este componente funciona como o botão para alternar a expansão de um item do acordeão.

Prop	Descrição
`itemId`	ID do item do acordeão
`class`	classe css adicional
`children`	conteúdo do rótulo do gatilho

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

O Conteúdo do Acordeão

Este componente exibe o conteúdo de cada item do acordeão quando expandido.

Prop	Descrição
`itemId`	ID do item do acordeão
`class`	classe css adicional
`children`	conteúdo a exibir quando 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 os Componentes

Por fim, exporte todos os componentes do acordeão e o context a partir de um único ponto de entrada para fornecer uma API pública limpa e 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 o Accordion

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

Construindo um Sistema de Notificações Toast

As abas e o accordion seguem padrões semelhantes: filhos estáticos declarados na marcação que se registram na montagem. Um sistema de toast introduz conceitos fundamentalmente diferentes — componentes criados dinamicamente em tempo de execução por meio de uma API imperativa.

O que Torna o Toast Diferente

Ao contrário das abas, onde você escreve <Tab id="x"> no seu template, os toasts são criados programaticamente:

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

	const toast = getToastContext()

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

Isso requer padrões de contexto diferentes:

Criação imperativa — Funções que adicionam novos itens ao estado
Temporizadores de auto-descarte — Limpeza agendada após uma duração
Renderização dinâmica — Iteração sobre uma coleção reativa
Viewport em posição fixa — Toasts aparecem fora do fluxo normal do documento
Gerenciamento do ciclo de vida dos temporizadores — Limpeza adequada para evitar vazamentos de memória

Estrutura do Projeto

O sistema de toast consiste em seis arquivos:

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

Primeiro, defina os tipos em um 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 do Toast

O contexto gerencia o estado dos toasts, os temporizadores e fornece a API imperativa. Usar uma classe encapsula o Map de temporizadores e garante a limpeza adequada:

// 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 Provider do Toast

O provider envolve sua aplicação e cria o 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 do Toast

O viewport renderiza todos os toasts ativos em uma posição fixa:

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

Toast individual com estilização e botão 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>

Exportações da API Pública

O arquivo index fornece uma interface pública limpa:

// 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 o Sistema de Toast

Configure o provider no seu layout raiz:

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

Use a API de toast em qualquer lugar da sua aplicação:

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

Principais Diferenças em Relação às Abas/Accordion

O sistema de toast demonstra padrões de componentes compostos fundamentalmente diferentes:

Aspecto	Abas/Accordion	Sistema de Toast
Filhos	Declarados na marcação	Criados em tempo de execução via API
Estilo de API	Composição declarativa	Chamadas de função imperativas
Ciclo de vida	Monta/desmonta com o pai	Auto-descarte temporizado
Renderização	Inline na árvore de componentes	Viewport em posição fixa
Formato do estado	ID ativo / Set de IDs	Array dinâmico de objetos
Registro	Componentes se auto-registram	Itens adicionados via `show()`
Limpeza	Automática na desmontagem	Gerenciamento explícito de temporizadores

O padrão de toast se aplica sempre que você precisar criar elementos de UI programaticamente — modais disparados por eventos, paletas de comandos, notificações dinâmicas ou qualquer sobreposição que não se encaixe naturalmente na hierarquia de componentes.

Padrões e Boas Práticas

Construir componentes compostos revela vários padrões importantes.

Registro de Componentes com Effects

Componentes filhos precisam se registrar no contexto pai quando são montados e cancelar o registro quando são desmontados. No Svelte 5, use $effect com uma função de limpeza:

<script>
	const tabs = getTabsContext()

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

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

Este padrão garante que o pai sempre saiba quais filhos existem, mesmo quando eles aparecem e desaparecem dinamicamente.

Estado Derivado para Verificações Reativas

Em vez de chamar funções no template, derive 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}>

Essa abordagem é mais limpa e garante que o valor seja atualizado sempre que as dependências mudarem.

Navegação por Teclado

Componentes compostos frequentemente precisam de suporte a teclado para acessibilidade. Trate isso no nível do contêiner:

<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

Atributos ARIA adequados tornam os componentes compostos acessíveis:

Abas:

Contêiner: role="tablist", aria-orientation
Aba: role="tab", aria-selected, aria-controls, tabindex
Painel: role="tabpanel", aria-labelledby

Accordion:

Gatilho: aria-expanded, aria-controls
Conteúdo: role="region", aria-labelledby, hidden

Vinculação por ID

Componentes referenciam uns aos outros por meio 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}"
>

Isso cria a conexão semântica que as tecnologias assistivas precisam.

Quando Usar Componentes Compostos

Componentes compostos funcionam bem quando:

Múltiplos componentes trabalham como uma unidade — Abas, accordions, menus, seletores dropdown
Flexibilidade na composição importa — Usuários precisam personalizar a estrutura ou adicionar elementos customizados
O estado interno deve ser ocultado — A complexidade do gerenciamento de estado fica dentro do sistema
Comportamento consistente é necessário — Todas as abas devem funcionar da mesma forma

Considere alternativas mais simples quando:

O componente é independente — Um único botão não precisa de padrões compostos
Props são suficientes — Se uma API simples de props cobre todos os casos de uso, não complique desnecessariamente
Os filhos não precisam de coordenação — Se os componentes filhos não interagem, o contexto adiciona complexidade desnecessária

Considerações de Performance

Componentes compostos podem escalar para casos de uso complexos, mas entender suas características de performance ajuda você a construir com eficiência.

Custo de Busca no Context

Cada componente filho chama getContext uma vez durante a inicialização. Para componentes compostos típicos com 5 a 20 filhos, esse custo é insignificante. No entanto, se você estiver renderizando centenas de itens (como uma lista virtualizada), considere se o padrão composto é apropriado.

<!-- ✅ 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, considere virtualização ou uma abordagem mais simples orientada a dados.

Conteúdo de Painel Lazy

Por padrão, nosso TabPanel só renderiza quando está ativo. Isso é eficiente — painéis inativos não existem no DOM:

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

No entanto, isso significa que o conteúdo é desmontado ao trocar de aba. Se os painéis contêm conteúdo caro de inicializar (formulários complexos, visualizações pesadas), considere mantê-los montados, porém 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>

O atributo inert impede interação via teclado com o conteúdo oculto.

Overhead de Registro

O padrão de registro (chamando registerTab no $effect) é executado para cada filho na montagem. Para listas dinâmicas que frequentemente adicionam/removem itens, considere agrupar em lote:

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

Isso agrupa múltiplos registros em uma única atualização de estado. Para a maioria dos casos de uso, essa otimização não é necessária — o Svelte já agrupa atualizações síncronas.

Limpeza de Timers de Toast

O sistema de toast cria timers para dispensa automática. Sempre limpe os timers quando os toasts forem dispensados ou o provider for desmontado:

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

Timers vazando podem causar problemas de memória e erros se dispararem após a desmontagem.

Conclusão

Componentes compostos representam o contexto em sua forma mais elegante. O padrão resolve um problema genuíno — como você constrói sistemas de UI flexíveis onde múltiplos componentes trabalham juntos sem forçar os desenvolvedores a conectar manualmente o gerenciamento de estado? A resposta é esconder a coordenação por trás de uma API composicional limpa. Os desenvolvedores organizam os componentes declarativamente, e o contexto cuida da comunicação interna.

O padrão de registro é central para fazer os componentes compostos funcionarem. Quando um Tab é montado, ele se registra no contexto de Tabs. Quando é desmontado, ele cancela o registro. Isso significa que o pai sempre sabe quais filhos existem, mesmo quando aparecem e desaparecem dinamicamente. O $effect com função de limpeza torna esse padrão natural no Svelte 5 — o efeito é executado na montagem para registrar, e sua função de limpeza é executada na desmontagem para cancelar o registro.

O que torna os componentes compostos particularmente valiosos é que eles movem a complexidade para o lugar certo. Navegação por teclado, atributos ARIA, gerenciamento de foco, sincronização de estado — tudo isso vive dentro do sistema de componentes compostos, implementado uma vez e funcionando para todos os usos. Os desenvolvedores que usam os componentes não precisam pensar nesses detalhes. Eles compõem as peças, e acessibilidade e comportamento vêm de graça. Esse é o objetivo de boas abstrações: esconder a complexidade enquanto expõe a flexibilidade.

Principais Aprendizados

Componentes compostos usam contexto para criar sistemas de UI flexíveis e combináveis:

O contexto fornece coordenação — O contêiner pai cria um contexto que os filhos consomem. Os filhos se registram, leem o estado compartilhado e disparam ações por meio do contexto.

Os componentes permanecem focados — Cada componente lida com uma responsabilidade. O contêiner gerencia o estado, os gatilhos lidam com a interação, o conteúdo lida com a exibição.

A composição permite flexibilidade — Os desenvolvedores organizam os componentes conforme necessário. Eles podem adicionar elementos personalizados, renderizar peças condicionalmente ou posicionar componentes em diferentes estruturas do DOM.

Padrões de registro rastreiam os filhos — Usando $effect com funções de limpeza, os filhos se registram na montagem e cancelam o registro na desmontagem. O pai sempre sabe o que existe.

Acessibilidade vem embutida — Atributos ARIA, navegação por teclado e gerenciamento de foco são tratados uma vez no sistema de componentes compostos, beneficiando todos os usos.

Os mesmos padrões se aplicam a muitos componentes de UI: menus, comboboxes, widgets de divulgação, sistemas de navegação e muito mais. Uma vez que você entenda o padrão, pode aplicá-lo em qualquer lugar onde múltiplos componentes precisem trabalhar juntos como um sistema coordenado.

O Que Vem a Seguir

Parabéns! Você concluiu a série sobre a Context API.

Agora você tem o conhecimento para construir arquiteturas sofisticadas baseadas em contexto no Svelte 5. Nos próximos artigos, reuniremos tudo com exemplos do mundo real usando padrões da Context API.

Gerenciamento de tema — Modo claro/escuro com preferências do sistema
Carrinho de compras — Carrinho de e-commerce com funcionalidade de adicionar/remover
Wizard de formulário de múltiplas etapas — Estado centralizado do formulário com validação
Sistema de autenticação — Estado de login do usuário e rotas protegidas
SaaS multi-tenant com Context API — Configurações e dados específicos do tenant

Componentes Que Funcionam como um Sistema

Entendendo Componentes Compostos

O Problema Que Eles Resolvem

A Solução dos Componentes Compostos

Como o Context Torna Isso Possível

Construindo o Sistema de Abas

Context das Abas

O Contêiner Tabs

A Lista de Abas

O Gatilho de Aba

O TabPanel

Exportando os Componentes

Usando as Abas

Construindo um Acordeão

Context do Acordeão

Tipos do Acordeão

O Contêiner Accordion

O Item do Acordeão

O Gatilho do Acordeão

O Conteúdo do Acordeão

Exportando os Componentes

Usando o Accordion

Construindo um Sistema de Notificações Toast

O que Torna o Toast Diferente

Estrutura do Projeto

Módulo de Tipos

Contexto do Toast

Componente Provider do Toast

Componente Viewport do Toast

Componente de Item Toast

Exportações da API Pública

Usando o Sistema de Toast

Principais Diferenças em Relação às Abas/Accordion

Padrões e Boas Práticas

Registro de Componentes com Effects

Estado Derivado para Verificações Reativas

Navegação por Teclado

Atributos ARIA

Vinculação por ID

Quando Usar Componentes Compostos

Considerações de Performance

Custo de Busca no Context

Conteúdo de Painel Lazy

Overhead de Registro

Limpeza de Timers de Toast

Conclusão

Principais Aprendizados

O Que Vem a Seguir

Veja Também

Recursos de Acessibilidade

Artigos Relacionados