Estilização Dinâmica com o Atributo `class`

Toda interface interativa precisa de estilização dinâmica. Pense nas experiências que você encontra diariamente: um link de navegação que se destaca quando você está naquela página, um botão que fica esmaecido enquanto um formulário está sendo enviado, um campo de entrada que fica vermelho quando a validação falha, ou um seletor de tema que alterna entre os modos claro e escuro. Todos esses padrões compartilham uma necessidade comum — adicionar e remover classes CSS com base no estado atual da sua aplicação.

Se você já trabalhou com JavaScript puro, sabe que isso pode ficar bagunçado rapidamente. Você acaba com chamadas de classList.add() e classList.remove() espalhadas por todo o seu código, tentando manter o DOM sincronizado com seus dados. Perca uma atualização, e sua UI fica fora de sincronia. O Svelte elimina completamente essa complexidade, deixando você descrever quais classes devem ser aplicadas quando — e o framework cuida do resto.

O Svelte 5 oferece duas abordagens para o gerenciamento dinâmico de classes. A primeira é o atributo class aprimorado, que ganhou suporte poderoso a objetos e arrays no Svelte 5.16. Esta é a abordagem moderna e recomendada, que lida com tudo, desde simples alternâncias até lógica complexa com múltiplas classes. A segunda é a diretiva class:, que era a forma original de aplicar classes condicionalmente em versões anteriores do Svelte.

Nota importante: A diretiva class: ainda funciona perfeitamente, mas agora é considerada legada. Você vai encontrá-la em tutoriais mais antigos, posts de blog e bases de código, portanto vale a pena entendê-la. No entanto, para qualquer novo código que você escrever, a sintaxe de objeto/array no atributo class é mais poderosa, mais combinável e a abordagem oficialmente recomendada.

Este tutorial irá guiá-lo por ambas as abordagens de forma abrangente. Começaremos com os fundamentos, evoluiremos para padrões complexos do mundo real e resolveremos os problemas mais comuns que os desenvolvedores enfrentam. Ao final, você terá total confiança para gerenciar classes CSS dinamicamente em qualquer aplicação Svelte 5.

O Problema: Por Que as Classes Dinâmicas Importam

Antes de mergulharmos na sintaxe do Svelte, vamos entender por que o gerenciamento dinâmico de classes é um desafio tão comum e por que a abordagem do Svelte é muito melhor do que o que você pode estar acostumado.

A Abordagem Tradicional com JavaScript

Imagine que você está construindo um botão de envio que precisa mostrar diferentes estados visuais: um estado "pronto" quando o usuário pode clicar, um estado "carregando" enquanto o formulário está sendo enviado, e um estado "desabilitado" quando o formulário é inválido. Em JavaScript puro, você pode escrever algo assim:

// Imperative approach - managing classes directly in JavaScript
function updateButtonState(button, isLoading, isDisabled) {
	// First, remove all possible state classes to start fresh
	button.classList.remove('loading', 'disabled', 'ready')

	// Then add the appropriate class based on current state
	if (isLoading) {
		button.classList.add('loading')
	} else if (isDisabled) {
		button.classList.add('disabled')
	} else {
		button.classList.add('ready')
	}
}

// You have to remember to call this every time state changes
submitButton.addEventListener('click', async () => {
	updateButtonState(submitButton, true, false) // Set loading state

	try {
		await submitForm()
		updateButtonState(submitButton, false, false) // Back to ready
	} catch (error) {
		updateButtonState(submitButton, false, true) // Show disabled/error
	}
})

Essa abordagem tem vários problemas que se tornam mais dolorosos conforme sua aplicação cresce:

Lógica espalhada: Seu código de gerenciamento de classes vive no JavaScript, completamente separado do seu HTML. Para entender como um elemento é estilizado, você precisa vasculhar vários arquivos e rastrear chamadas de funções.
Sincronização manual: Toda vez que seu estado muda, você deve se lembrar de chamar a função de atualização. Esqueça uma chamada, e sua UI mostrará o estado errado. Esta é uma fonte constante de bugs.
Manutenção propensa a erros: O que acontece quando você adiciona um quarto estado? Você precisa encontrar todos os lugares que chamam updateButtonState, atualizar a assinatura da função e garantir que a nova classe seja removida na etapa de limpeza. Perca qualquer um desses passos, e você terá bugs sutis.
Baixa legibilidade: Olhando apenas para o HTML, você não tem ideia de quais classes podem ser aplicadas dinamicamente. A conexão entre seus dados e sua estilização é invisível.

A Solução Declarativa do Svelte

Agora vamos ver como o Svelte lida com exatamente o mesmo requisito. Em vez de dizer imperativamente ao DOM o que fazer, você descreve declarativamente o que deve ser verdade com base no seu estado:

<script>
	let isLoading = $state(false)
	let isDisabled = $state(false)
</script>

<button
	class={{
		loading: isLoading,
		disabled: isDisabled && !isLoading,
		ready: !isLoading && !isDisabled
	}}
>
	Submit
</button>

<style>
	button {
		padding: 0.75rem 1.5rem;
		border: none;
		border-radius: 6px;
		font-weight: 500;
		cursor: pointer;
		transition: all 0.2s ease;
	}

	.ready {
		background-color: #3b82f6;
		color: white;
	}

	.ready:hover {
		background-color: #2563eb;
	}

	.loading {
		background-color: #9ca3af;
		color: white;
		cursor: wait;
	}

	.disabled {
		background-color: #e5e7eb;
		color: #9ca3af;
		cursor: not-allowed;
	}
</style>

Veja como isso é muito mais limpo! A relação entre estado e estilização é cristalina, bem ali no template onde você pode vê-la. Quando isLoading é true, o botão recebe a classe loading. Quando tanto isLoading quanto isDisabled são false, ele recebe a classe ready. Não há função para chamar, nenhuma sincronização para gerenciar — o Svelte observa seu estado reativo e atualiza o DOM automaticamente sempre que algo muda.

Essa abordagem declarativa significa que você pode se concentrar no que você quer, não no como fazer acontecer. Seu código fica mais curto, mais legível e muito menos propenso a bugs. Agora vamos aprender a usar esse poder de forma eficaz.

O Atributo `class`: Sua Fundação

O atributo class no Svelte funciona exatamente como você esperaria do HTML, com algumas melhorias poderosas. Vamos começar com o básico e evoluir para padrões mais sofisticados.

Classes Estáticas: Igual ao HTML

Em sua forma mais simples, o atributo class funciona exatamente como o HTML comum. Se você só precisa de classes estáticas que nunca mudam, escreva-as como uma string simples:

<div class="container">This works exactly like regular HTML</div>

<button class="btn primary rounded"> Static classes only </button>

<style>
	.container {
		max-width: 1200px;
		margin: 0 auto;
		padding: 1rem;
	}

	.btn {
		padding: 0.5rem 1rem;
		border: none;
		cursor: pointer;
	}

	.primary {
		background-color: #3b82f6;
		color: white;
	}

	.rounded {
		border-radius: 8px;
	}
</style>

Nada de especial aqui — essas classes são aplicadas quando o componente é montado e nunca mudam. Mas é claro, não é por isso que você está lendo este tutorial. Vamos tornar as coisas dinâmicas.

Classes Dinâmicas com Expressões

Quando você envolve o valor do class em chaves {}, pode usar qualquer expressão JavaScript. O caso mais simples é usar uma variável:

<script>
	let currentSize = $state('large')
</script>

<div class={currentSize}>This div has class="large"</div>

<style>
	.small {
		font-size: 0.875rem;
		padding: 0.5rem;
	}

	.medium {
		font-size: 1rem;
		padding: 1rem;
	}

	.large {
		font-size: 1.25rem;
		padding: 1.5rem;
	}
</style>

Quando currentSize é 'large', a div recebe class="large". Se você posteriormente mudar currentSize para 'small', o Svelte atualiza automaticamente o DOM para class="small". Sem intervenção manual necessária.

Você também pode usar expressões mais complexas, como operadores ternários, para escolher entre duas classes possíveis:

<script>
	let isExpanded = $state(false)
</script>

<div class={isExpanded ? 'panel-expanded' : 'panel-collapsed'}>
	<p>Panel content goes here</p>
</div>

<button onclick={() => (isExpanded = !isExpanded)}>
	{isExpanded ? 'Collapse' : 'Expand'} Panel
</button>

<style>
	.panel-expanded {
		max-height: 500px;
		padding: 1.5rem;
		opacity: 1;
		transition: all 0.3s ease;
	}

	.panel-collapsed {
		max-height: 0;
		padding: 0 1.5rem;
		opacity: 0;
		overflow: hidden;
		transition: all 0.3s ease;
	}

	button {
		margin-top: 1rem;
		padding: 0.5rem 1rem;
		background: #4b5563;
		color: white;
		border: none;
		border-radius: 4px;
		cursor: pointer;
	}
</style>

Toda vez que você clica no botão, isExpanded alterna entre true e false, e a classe da div é atualizada de acordo. O operador ternário (condição ? valorSeVerdadeiro : valorSeFalso) é perfeito quando você precisa escolher entre exatamente duas classes.

Entendendo Valores Falsy

Antes de prosseguirmos, é importante entender como o Svelte lida com valores "falsy" no atributo class. Em JavaScript, certos valores são considerados "falsy" — eles avaliam para false em contextos booleanos. Esses incluem false, 0, '' (string vazia), null, undefined e NaN.

O Svelte lida com eles de forma diferente dependendo do que são:

<script>
	let nullClass = null
	let undefinedClass = undefined
	let falseClass = false
	let emptyString = ''
	let zero = 0
</script>

<!-- null and undefined: the class attribute is omitted entirely -->
<div class={nullClass}>No class attribute at all</div>
<div class={undefinedClass}>No class attribute at all</div>

<!-- Other falsy values get converted to strings (probably not what you want!) -->
<div class={falseClass}>class="false" - oops!</div>
<div class={zero}>class="0" - probably not intended</div>
<div class={emptyString}>class="" - empty but present</div>

Esse comportamento existe por razões históricas, mas é importante estar ciente dele. Se sua expressão pode avaliar para false ou outro valor falsy, você precisa lidar com esse caso explicitamente — ou melhor ainda, use a sintaxe de objeto/array que aprenderemos a seguir, que lida com valores falsy de forma elegante.

Olhando adiante: Uma versão futura do Svelte fará com que todos os valores falsy omitam o atributo class completamente, tornando o comportamento mais consistente. Mas por ora, null e undefined são suas opções mais seguras quando você quer omitir o atributo condicionalmente.

Sintaxe de Objeto: Controle Granular de Classes

A partir do Svelte 5.16, o atributo class ganhou a capacidade de aceitar objetos. Isso é revolucionário para o gerenciamento dinâmico de classes, e é a abordagem que você deve usar na maioria das situações. Internamente, o Svelte usa a popular biblioteca clsx para processar esses objetos.

Como Funciona a Sintaxe de Objeto

A ideia básica é simples: você passa um objeto onde as chaves são nomes de classes e os valores são booleanos (ou expressões que avaliam para valores truthy/falsy). Se o valor é truthy, a classe é aplicada. Se é falsy, a classe não é aplicada.

<script>
	let isActive = $state(true)
	let isDisabled = $state(false)
	let isHighlighted = $state(true)
</script>

<div class={{ active: isActive, disabled: isDisabled, highlighted: isHighlighted }}>
	This div will have classes: "active highlighted"
</div>

<style>
	div {
		padding: 1rem;
		border: 2px solid #e5e7eb;
		border-radius: 8px;
		transition: all 0.2s ease;
	}

	.active {
		border-color: #3b82f6;
		background-color: #eff6ff;
	}

	.disabled {
		opacity: 0.5;
		pointer-events: none;
		background-color: #f3f4f6;
	}

	.highlighted {
		box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.3);
	}
</style>

Vamos analisar o que está acontecendo aqui:

active: isActive — Como isActive é true, a classe active é aplicada
disabled: isDisabled — Como isDisabled é false, a classe disabled NÃO é aplicada
highlighted: isHighlighted — Como isHighlighted é true, a classe highlighted é aplicada

O HTML resultante é <div class="active highlighted">. Se você posteriormente definir isDisabled = true e isHighlighted = false, o Svelte atualiza automaticamente o DOM para <div class="active disabled">.

Esse padrão é incrivelmente poderoso porque cada classe é controlada independentemente por sua própria condição. Você não precisa pensar em remover classes antigas ou gerenciar transições de estado — você apenas descreve o que deve ser verdade agora.

Abreviação de Propriedade JavaScript

Quando o nome da sua variável corresponde ao nome da classe que você quer aplicar, a abreviação de propriedade do JavaScript torna as coisas ainda mais limpas:

<script>
	// Variable names match the class names we want
	let active = $state(true)
	let disabled = $state(false)
	let loading = $state(false)
</script>

<!-- Using shorthand syntax -->
<button class={{ active, disabled, loading }}>
	<!-- Equivalent to: class={{ active: active, disabled: disabled, loading: loading }} -->
	Click me
</button>

<style>
	button {
		padding: 0.75rem 1.5rem;
		border: 2px solid #3b82f6;
		background: white;
		color: #3b82f6;
		border-radius: 6px;
		font-weight: 500;
		cursor: pointer;
		transition: all 0.2s ease;
	}

	.active {
		background: #3b82f6;
		color: white;
	}

	.disabled {
		opacity: 0.5;
		cursor: not-allowed;
		border-color: #9ca3af;
		color: #9ca3af;
	}

	.loading {
		cursor: wait;
		position: relative;
	}

	.loading::after {
		content: '';
		position: absolute;
		width: 1rem;
		height: 1rem;
		border: 2px solid transparent;
		border-top-color: currentColor;
		border-radius: 50%;
		animation: spin 0.6s linear infinite;
		right: 0.5rem;
	}

	@keyframes spin {
		to {
			transform: rotate(360deg);
		}
	}
</style>

Essa abreviação é apenas sintaxe comum de objeto JavaScript — { active } é exatamente o mesmo que { active: active }. É algo pequeno, mas torna seu código mais limpo e reduz a repetição.

Usando Expressões como Valores

Os valores no seu objeto não precisam ser simples variáveis booleanas. Você pode usar qualquer expressão que avalie para um valor truthy ou falsy:

<script>
	let itemCount = $state(5)
	let userRole = $state('admin')
	let errorMessage = $state('')
</script>

<div
	class={{
		'has-items': itemCount > 0,
		'is-empty': itemCount === 0,
		'is-admin': userRole === 'admin',
		'is-moderator': userRole === 'moderator',
		'has-error': errorMessage.length > 0
	}}
>
	<p>Items: {itemCount}</p>
	<p>Role: {userRole}</p>
</div>

<style>
	div {
		padding: 1rem;
		border-radius: 8px;
		border: 2px solid #e5e7eb;
	}

	.has-items {
		background-color: #f0fdf4;
		border-color: #86efac;
	}

	.is-empty {
		background-color: #fef2f2;
		border-color: #fca5a5;
	}

	.is-admin {
		border-left: 4px solid #8b5cf6;
	}

	.is-moderator {
		border-left: 4px solid #f59e0b;
	}

	.has-error {
		background-color: #fef2f2;
		border-color: #ef4444;
	}
</style>

Cada par chave-valor é avaliado independentemente. A classe has-items é aplicada porque itemCount > 0 é true (5 > 0). A classe is-admin é aplicada porque userRole === 'admin' é true. A classe has-error NÃO é aplicada porque errorMessage.length > 0 é false (string vazia tem comprimento 0).

Nomes de Classes Dinâmicos com Chaves Computadas

Às vezes você precisa que o próprio nome da classe seja dinâmico, não apenas se ela é aplicada. Você pode usar a sintaxe de propriedade computada do JavaScript (colchetes) para criar nomes de classes a partir de expressões:

<script>
	let theme = $state('dark')
	let size = $state('large')
	let variant = $state('primary')
</script>

<button
	class={{
		[`theme-${theme}`]: true,
		[`size-${size}`]: true,
		[`variant-${variant}`]: true
	}}
>
	Dynamically named classes
</button>

<!-- Result: class="theme-dark size-large variant-primary" -->

<style>
	button {
		border: none;
		border-radius: 6px;
		font-weight: 500;
		cursor: pointer;
	}

	/* Theme classes */
	.theme-light {
		background-color: #f9fafb;
		color: #1f2937;
	}

	.theme-dark {
		background-color: #1f2937;
		color: #f9fafb;
	}

	/* Size classes */
	.size-small {
		padding: 0.375rem 0.75rem;
		font-size: 0.875rem;
	}

	.size-medium {
		padding: 0.5rem 1rem;
		font-size: 1rem;
	}

	.size-large {
		padding: 0.75rem 1.5rem;
		font-size: 1.125rem;
	}

	/* Variant classes */
	.variant-primary {
		background-color: #3b82f6;
		color: white;
	}

	.variant-secondary {
		background-color: #6b7280;
		color: white;
	}

	.variant-danger {
		background-color: #ef4444;
		color: white;
	}
</style>

Os colchetes dizem ao JavaScript para avaliar a expressão dentro e usar o resultado como a chave da propriedade. Então [`theme-${theme}`] se torna 'theme-dark' quando theme é 'dark'. O valor true significa "sempre aplicar esta classe."

Isso é particularmente útil quando você está trabalhando com um sistema de design que usa convenções de nomenclatura como variant-primary, size-lg ou theme-dark.

Aplicando Múltiplas Classes com Uma Única Condição

Uma das funcionalidades mais poderosas da sintaxe de objeto é a capacidade de alternar múltiplas classes com uma única condição. Basta colocar todos os nomes de classes na chave, separados por espaços:

<script>
	let isError = $state(false)
	let isSuccess = $state(false)
	let isLoading = $state(true)
</script>

<div
	class={{
		'loading pulse': isLoading,
		'error shake': isError,
		'success fade-in': isSuccess
	}}
>
	{#if isLoading}
		Loading...
	{:else if isError}
		Something went wrong!
	{:else if isSuccess}
		Operation completed successfully!
	{:else}
		Ready
	{/if}
</div>

<style>
	div {
		padding: 1rem;
		border-radius: 8px;
		text-align: center;
		font-weight: 500;
	}

	/* Loading state styles */
	.loading {
		background-color: #f3f4f6;
		color: #6b7280;
	}

	.pulse {
		animation: pulse 1.5s ease-in-out infinite;
	}

	@keyframes pulse {
		0%,
		100% {
			opacity: 1;
		}
		50% {
			opacity: 0.5;
		}
	}

	/* Error state styles */
	.error {
		background-color: #fef2f2;
		color: #dc2626;
		border: 1px solid #fca5a5;
	}

	.shake {
		animation: shake 0.5s ease-in-out;
	}

	@keyframes shake {
		0%,
		100% {
			transform: translateX(0);
		}
		25% {
			transform: translateX(-5px);
		}
		75% {
			transform: translateX(5px);
		}
	}

	/* Success state styles */
	.success {
		background-color: #f0fdf4;
		color: #16a34a;
		border: 1px solid #86efac;
	}

	.fade-in {
		animation: fadeIn 0.3s ease-in;
	}

	@keyframes fadeIn {
		from {
			opacity: 0;
		}
		to {
			opacity: 1;
		}
	}
</style>

Quando isLoading é true, ambas as classes (loading e pulse) são aplicadas juntas. Quando se torna false, ambas são removidas juntas. Isso facilita agrupar estilos relacionados — a aparência visual e a animação andam juntas.

Pense nisso: da forma antiga, você precisaria de lógica separada para cada classe. Com a sintaxe de objeto, classes relacionadas são agrupadas pela sua condição, tornando sua intenção cristalina.

Sintaxe de Array: Combinando Múltiplas Fontes de Classe

Enquanto a sintaxe de objeto é ótima para alternâncias booleanas, a sintaxe de array se destaca quando você precisa combinar múltiplas fontes de classes ou usar lógica condicional mais complexa. Assim como os objetos, os arrays são processados pelo clsx e todos os valores falsy são automaticamente filtrados.

Como a Sintaxe de Array Funciona

Com a sintaxe de array, você fornece um array de valores. Cada valor pode ser uma string (que é sempre incluída) ou uma expressão que avalia para uma string (incluída) ou um valor falsy (excluído):

<script>
	let isPrimary = $state(true)
	let isLarge = $state(false)
	let isDisabled = $state(false)
</script>

<button
	class={['btn', 'rounded', isPrimary && 'primary', isLarge && 'large', isDisabled && 'disabled']}
>
	Click me
</button>

<!-- Result: class="btn rounded primary" -->

<style>
	.btn {
		padding: 0.5rem 1rem;
		border: none;
		font-weight: 500;
		cursor: pointer;
		transition: all 0.2s ease;
	}

	.rounded {
		border-radius: 6px;
	}

	.primary {
		background-color: #3b82f6;
		color: white;
	}

	.primary:hover {
		background-color: #2563eb;
	}

	.large {
		padding: 0.75rem 1.5rem;
		font-size: 1.125rem;
	}

	.disabled {
		opacity: 0.5;
		cursor: not-allowed;
		pointer-events: none;
	}
</style>

Vamos analisar cada elemento:

'btn' — Uma string simples, sempre incluída
'rounded' — Outra string simples, sempre incluída
isPrimary && 'primary' — isPrimary é true, portanto avalia para 'primary' (incluído)
isLarge && 'large' — isLarge é false, portanto avalia para false (excluído)
isDisabled && 'disabled' — isDisabled é false, portanto avalia para false (excluído)

A mágica está em como o operador && do JavaScript funciona: se o lado esquerdo é falsy, ele retorna o lado esquerdo (que é filtrado). Se o lado esquerdo é truthy, ele retorna o lado direito (o nome da classe). Esse padrão é tão comum em React e Svelte que vale a pena memorizar.

Grupos de Classes Condicionais com Operadores Ternários

Às vezes você precisa escolher entre dois conjuntos de classes diferentes, não apenas incluir ou excluir uma única classe. Operadores ternários funcionam perfeitamente dentro de arrays:

<script>
	let status = $state('loading')
</script>

<div
	class={[
		'status-card',
		status === 'loading'
			? 'loading'
			: status === 'error'
				? 'error'
				: status === 'success'
					? 'success'
					: 'idle'
	]}
>
	<span class="status-icon">
		{#if status === 'loading'}
			⏳
		{:else if status === 'error'}
			❌
		{:else if status === 'success'}
			✅
		{:else}
			💤
		{/if}
	</span>
	<span class="status-text">Status: {status}</span>
</div>

<style>
	.status-card {
		display: flex;
		align-items: center;
		gap: 0.75rem;
		padding: 1rem;
		border-radius: 8px;
		border: 2px solid;
	}

	.status-icon {
		font-size: 1.5rem;
	}

	.status-text {
		font-weight: 500;
		text-transform: capitalize;
	}

	.loading {
		background-color: #f3f4f6;
		border-color: #d1d5db;
		color: #6b7280;
	}

	.error {
		background-color: #fef2f2;
		border-color: #fca5a5;
		color: #dc2626;
	}

	.success {
		background-color: #f0fdf4;
		border-color: #86efac;
		color: #16a34a;
	}

	.idle {
		background-color: #f9fafb;
		border-color: #e5e7eb;
		color: #374151;
	}
</style>

A classe base (status-card) é sempre aplicada. Em seguida, dependendo do valor de status, diferentes classes de estilo são adicionadas. Isso cria um mapeamento limpo entre estado e apresentação.

Para melhor legibilidade com múltiplos estados, você pode preferir múltiplas condições:

<div
	class={[
		'status-card',
		status === 'loading' && 'loading',
		status === 'error' && 'error',
		status === 'success' && 'success',
		status === 'idle' && 'idle'
	]}
>
	<!-- content -->
</div>

Ambas as abordagens funcionam; escolha a que for mais clara para o seu caso específico. Quando os estados são mutuamente exclusivos (apenas um pode ser verdadeiro por vez), a segunda abordagem com condições separadas costuma ser mais legível.

Aninhando Arrays e Objetos

Um dos recursos mais poderosos do clsx (e, portanto, do tratamento de classes do Svelte) é que arrays podem conter outros arrays e até objetos. Tudo é achatado e processado corretamente:

<script>
	// Base classes that multiple elements might share
	const cardBase = ['card', 'rounded', 'shadow']
	const interactiveStyles = ['clickable', 'hoverable']

	let isSelected = $state(false)
	let variant = $state('default')
</script>

<button
	type="button"
	class={[
		cardBase,
		interactiveStyles,
		{ selected: isSelected, ring: isSelected },
		variant === 'featured' && 'featured'
	]}
	onclick={() => (isSelected = !isSelected)}
	aria-pressed={isSelected}
>
	<h3>Card Title</h3>
	<p>A card that combines multiple class sources. Click to select!</p>
</button>

<style>
	button.card {
		padding: 1.5rem;
		background: white;
		border: 1px solid #e5e7eb;
		text-align: left;
		width: 100%;
		font: inherit;
	}

	.rounded {
		border-radius: 12px;
	}

	.shadow {
		box-shadow:
			0 4px 6px -1px rgb(0 0 0 / 0.1),
			0 2px 4px -2px rgb(0 0 0 / 0.1);
	}

	.clickable {
		cursor: pointer;
		user-select: none;
	}

	.hoverable {
		transition: all 0.2s ease;
	}

	.hoverable:hover {
		transform: translateY(-2px);
		box-shadow:
			0 10px 15px -3px rgb(0 0 0 / 0.1),
			0 4px 6px -4px rgb(0 0 0 / 0.1);
	}

	.selected {
		border-color: #3b82f6;
		background-color: #eff6ff;
	}

	.ring {
		box-shadow:
			0 0 0 3px rgba(59, 130, 246, 0.3),
			0 4px 6px -1px rgb(0 0 0 / 0.1);
	}

	.featured {
		border-width: 2px;
		border-color: #f59e0b;
	}

	h3 {
		margin: 0 0 0.5rem;
		font-size: 1.125rem;
		color: #111827;
	}

	p {
		margin: 0;
		color: #6b7280;
	}
</style>

Este exemplo demonstra vários conceitos funcionando juntos:

Arrays de classes reutilizáveis (cardBase, interactiveStyles) que podem ser compartilhados entre componentes
Um objeto embutido para classes baseadas em alternância
Uma expressão condicional para classes específicas de variante

Tudo é achatado em uma única string de classes. Essa composabilidade é incrivelmente poderosa para construir sistemas de design onde você quer compartilhar estilos base permitindo personalização.

Composição de Classes em Componentes

Ao construir componentes reutilizáveis, você frequentemente vai querer permitir que os consumidores adicionem suas próprias classes enquanto preserva o estilo base do componente. É aqui que o tratamento de classes do Svelte 5 realmente se destaca.

O Desafio: Aceitar Classes Externas

Imagine que você está construindo um componente Button. Ele tem seus próprios estilos, mas você quer que os usuários possam adicionar classes extras para espaçamento, dimensionamento ou estilização personalizada sem modificar o componente em si. Veja como fazer isso:

<!-- Button.svelte -->
<script>
	let { class: className, variant = 'primary', children } = $props()
</script>

<button
	class={[
		'btn',
		variant === 'primary' && 'primary',
		variant === 'secondary' && 'secondary',
		variant === 'ghost' && 'ghost',
		className
	]}
>
	{@render children?.()}
</button>

<style>
	.btn {
		padding: 0.625rem 1.25rem;
		border: 2px solid transparent;
		border-radius: 6px;
		font-weight: 500;
		font-size: 1rem;
		cursor: pointer;
		transition: all 0.2s ease;
	}

	.btn:focus {
		outline: none;
		box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.4);
	}

	.primary {
		background-color: #3b82f6;
		color: white;
	}

	.primary:hover {
		background-color: #2563eb;
	}

	.secondary {
		background-color: #e5e7eb;
		color: #374151;
	}

	.secondary:hover {
		background-color: #d1d5db;
	}

	.ghost {
		background-color: transparent;
		color: #374151;
		border-color: #e5e7eb;
	}

	.ghost:hover {
		background-color: #f3f4f6;
	}
</style>

Observe algumas coisas importantes:

Renomeamos a prop: Usamos class: className porque class é uma palavra reservada em JavaScript. Isso desestrutura a prop class em uma variável chamada className.
Colocamos className por último: Isso é intencional! Ao colocar as classes do usuário por último, permitimos que eles adicionem estilização adicional que funciona junto com nossos estilos base.
O componente define seus estilos base: O botão sempre tem a classe btn. Esses são os estilos base inegociáveis.
Classes de variante são condicionais: Dependendo da prop variant, diferentes classes de cor/estilo são aplicadas.

Agora os consumidores podem usar o componente assim:

<script>
	import Button from './Button.svelte'
</script>

<!-- Basic usage -->
<Button>Click me</Button>

<!-- With custom classes -->
<Button class="extra-margin">With spacing</Button>

<!-- Different variant with custom classes -->
<Button variant="secondary" class="full-width">Secondary button</Button>

<style>
	.extra-margin {
		margin-top: 1rem;
	}

	.full-width {
		width: 100%;
	}
</style>

Tipos de Entrada Flexíveis

Uma das coisas belas no tratamento de classes do Svelte é que os consumidores podem passar classes como strings, objetos ou arrays — o que for mais conveniente para o seu caso de uso:

<script>
	import Button from './Button.svelte'

	let isLoading = $state(false)
	let isFullWidth = $state(true)
</script>

<!-- String (simplest) -->
<Button class="custom-class">String classes</Button>

<!-- Object (for conditional classes) -->
<Button class={{ loading: isLoading, 'full-width': isFullWidth }}>Object classes</Button>

<!-- Array (for complex combinations) -->
<Button class={['spaced', isFullWidth && 'full-width', isLoading && 'loading']}>
	Array classes
</Button>

<style>
	:global(.custom-class) {
		border-style: dashed;
	}

	:global(.loading) {
		opacity: 0.7;
		cursor: wait;
	}

	:global(.full-width) {
		width: 100%;
	}

	:global(.spaced) {
		margin: 0.5rem;
	}
</style>

Como tudo passa pelo clsx, todos esses formatos funcionam perfeitamente. Seu componente não precisa fazer nada especial — apenas inclua className no seu array de classes e o Svelte cuida do resto.

Suporte a TypeScript com ClassValue

Se você estiver usando TypeScript, vai querer tipar corretamente suas props de classe. O Svelte 5.19 introduziu o tipo ClassValue especificamente para esse propósito:

<script lang="ts">
	import type { ClassValue } from 'svelte/elements'
	import type { Snippet } from 'svelte'

	interface Props {
		class?: ClassValue
		variant?: 'primary' | 'secondary' | 'ghost'
		disabled?: boolean
		children?: Snippet
	}

	let { class: className, variant = 'primary', disabled = false, children }: Props = $props()
</script>

<button class={['btn', `variant-${variant}`, disabled && 'disabled', className]} {disabled}>
	{@render children?.()}
</button>

<style>
	.btn {
		padding: 0.625rem 1.25rem;
		border: none;
		border-radius: 6px;
		font-weight: 500;
		cursor: pointer;
	}

	.variant-primary {
		background-color: #3b82f6;
		color: white;
	}

	.variant-secondary {
		background-color: #e5e7eb;
		color: #374151;
	}

	.variant-ghost {
		background-color: transparent;
		border: 2px solid #e5e7eb;
		color: #374151;
	}

	.disabled {
		opacity: 0.5;
		cursor: not-allowed;
		pointer-events: none;
	}
</style>

O tipo ClassValue aceita strings, objetos, arrays e qualquer combinação aninhada deles — exatamente o que o tratamento de classes do Svelte suporta. Isso oferece total segurança de tipos enquanto mantém flexibilidade completa.

A Diretiva `class:` (Sintaxe Legada)

Antes do Svelte 5.16 adicionar suporte a objetos e arrays no atributo class, a diretiva class: era a única forma de aplicar classes condicionalmente. Embora ainda funcione perfeitamente, agora é considerada sintaxe legada. Você deve usar a sintaxe de objeto/array para novo código, mas entender a diretiva é valioso, pois você vai encontrá-la em bases de código antigas, tutoriais e respostas no Stack Overflow.

Como a Diretiva Funciona

A diretiva class: segue o padrão class:name={condition}, onde name é a classe a ser aplicada e condition é uma expressão booleana:

<script>
	let isActive = $state(true)
	let isDisabled = $state(false)
	let isLoading = $state(false)
</script>

<button class:active={isActive} class:disabled={isDisabled} class:loading={isLoading}>
	Click me
</button>

<!-- When isActive is true: class="active" -->

<style>
	button {
		padding: 0.75rem 1.5rem;
		border: 2px solid #3b82f6;
		background: white;
		color: #3b82f6;
		border-radius: 6px;
		cursor: pointer;
	}

	.active {
		background: #3b82f6;
		color: white;
	}

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

	.loading {
		cursor: wait;
	}
</style>

Quando a condição é truthy, a classe é adicionada. Quando é falsy, a classe é removida. Simples o suficiente, mas observe como cada classe precisa de sua própria diretiva. Compare isso com a sintaxe de objeto:

<!-- Object syntax: one attribute, all conditions together -->
<button class={{ active: isActive, disabled: isDisabled, loading: isLoading }}> Click me </button>

<!-- Directive syntax: separate directive for each class -->
<button class:active={isActive} class:disabled={isDisabled} class:loading={isLoading}>
	Click me
</button>

Ambas produzem o mesmo resultado, mas a sintaxe de objeto é mais compacta e mantém toda a lógica de classes em um único lugar.

Sintaxe Abreviada

Quando o nome da sua variável corresponde exatamente ao nome da classe que você deseja aplicar, você pode usar uma forma abreviada que omite o valor:

<script>
	let active = $state(true)
	let disabled = $state(false)
	let highlighted = $state(true)
</script>

<!-- Shorthand: class:name is equivalent to class:name={name} -->
<div class:active class:disabled class:highlighted>Content</div>

<!-- Result: class="active highlighted" -->

<style>
	div {
		padding: 1rem;
		border: 2px solid #e5e7eb;
		border-radius: 8px;
	}

	.active {
		border-color: #3b82f6;
	}

	.disabled {
		opacity: 0.5;
	}

	.highlighted {
		background-color: #fef3c7;
	}
</style>

Isso só funciona quando o nome da variável e o nome da classe são idênticos. É uma conveniência útil, mas restringe a nomenclatura das suas variáveis.

Combinando a Diretiva com Classes Estáticas

Você pode usar a diretiva class: junto com um atributo class regular para classes estáticas:

<script>
	let isSelected = $state(false)
</script>

<div class="card" class:selected={isSelected} class:highlighted={isSelected}>
	A card that might be selected
</div>

<style>
	.card {
		padding: 1.5rem;
		border-radius: 12px;
		border: 2px solid #e5e7eb;
		background: white;
		box-shadow: 0 1px 3px rgb(0 0 0 / 0.1);
	}

	.selected {
		border-color: #3b82f6;
		background-color: #eff6ff;
	}

	.highlighted {
		box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.3);
	}
</style>

As classes estáticas (card) estão sempre presentes. As classes controladas pela diretiva (selected, highlighted) são adicionadas ou removidas com base em isSelected.

Por Que a Sintaxe de Objeto/Array é Melhor

A sintaxe de diretiva tem várias limitações que a sintaxe moderna resolve:

Sem condições para múltiplas classes: Você não pode alternar múltiplas classes com uma única diretiva. Cada classe precisa de sua própria diretiva.
Mais verbosa: Cinco classes condicionais significam cinco diretivas separadas poluindo seu elemento.
Não é composável: Você não pode facilmente combinar classes de diretiva com classes passadas como props.
Mistura duas sintaxes: Usar tanto class="..." quanto class:name no mesmo elemento pode ser confuso.

A sintaxe de objeto/array resolve todos esses problemas. Use-a para novo código e considere migrar código legado quando estiver fazendo outras alterações nesses componentes.

Padrões e Exemplos do Mundo Real

Vamos ver alguns exemplos completos e práticos que demonstram como usar classes dinâmicas em aplicações reais.

1. Navegação com Estado Ativo

Quase toda aplicação precisa de navegação que destaque a página atual. Aqui está uma implementação completa e acessível:

<script>
	import { page } from '$app/stores'

	const navItems = [
		{ href: '/', label: 'Home', icon: '🏠' },
		{ href: '/products', label: 'Products', icon: '📦' },
		{ href: '/about', label: 'About', icon: 'ℹ️' },
		{ href: '/contact', label: 'Contact', icon: '✉️' }
	]
</script>

<nav aria-label="Main navigation">
	<ul class="nav-list">
		{#each navItems as item}
			{@const isActive = $page.url.pathname === item.href}
			<li>
				<a
					href={item.href}
					class={['nav-link', isActive && 'active']}
					aria-current={isActive ? 'page' : undefined}
				>
					<span class="nav-icon" aria-hidden="true">{item.icon}</span>
					<span class="nav-label">{item.label}</span>
				</a>
			</li>
		{/each}
	</ul>
</nav>

<style>
	nav {
		background: white;
		border-bottom: 1px solid #e5e7eb;
		box-shadow: 0 1px 3px rgb(0 0 0 / 0.05);
	}

	.nav-list {
		display: flex;
		gap: 0.25rem;
		list-style: none;
		margin: 0;
		padding: 0 1rem;
		max-width: 1200px;
		margin: 0 auto;
	}

	.nav-link {
		display: flex;
		align-items: center;
		gap: 0.5rem;
		padding: 1rem;
		text-decoration: none;
		color: #6b7280;
		font-weight: 500;
		border-bottom: 3px solid transparent;
		transition: all 0.2s ease;
	}

	.nav-link:hover {
		color: #374151;
		background-color: #f9fafb;
	}

	.nav-link.active {
		color: #2563eb;
		border-bottom-color: #2563eb;
		background-color: #eff6ff;
	}

	.nav-icon {
		font-size: 1.25rem;
	}

	.nav-label {
		font-size: 0.9375rem;
	}
</style>

Pontos-chave neste exemplo:

Usamos @const para calcular isActive uma vez por iteração, mantendo o template limpo
O atributo aria-current="page" é aplicado condicionalmente para acessibilidade
Itens ativos recebem uma borda inferior visível, texto colorido e um fundo sutil
Itens inativos possuem estados de hover que antecipam como será o estado ativo
O ícone é marcado com aria-hidden por ser decorativo

2. Validação de Formulário com Feedback Visual

Inputs de formulário precisam comunicar seu estado de validação de forma clara. Aqui está um componente de input completo com estilização de validação:

<script>
	let value = $state('')
	let touched = $state(false)
	let focused = $state(false)

	// Validation logic
	let isEmpty = $derived(value.trim().length === 0)
	let isTooShort = $derived(value.trim().length > 0 && value.trim().length < 3)
	let isValid = $derived(value.trim().length >= 3)

	// Determine what to show (only after user has interacted)
	let showError = $derived(touched && !focused && !isValid)
	let showSuccess = $derived(touched && isValid)

	// Error message to display
	let errorMessage = $derived.by(() => {
		if (!touched || focused) return ''
		if (isEmpty) return 'This field is required'
		if (isTooShort) return 'Must be at least 3 characters'
		return ''
	})
</script>

<div class="form-field">
	<label for="username">Username</label>

	<div class="input-wrapper">
		<input
			id="username"
			type="text"
			bind:value
			onfocus={() => (focused = true)}
			onblur={() => {
				focused = false
				touched = true
			}}
			class={[
				'input',
				showError && 'error',
				showSuccess && 'success',
				!showError && !showSuccess && 'neutral'
			]}
			aria-invalid={showError}
			aria-describedby={showError ? 'username-error' : undefined}
		/>

		{#if showSuccess}
			<span class="success-icon">✓</span>
		{/if}
	</div>

	{#if showError}
		<p id="username-error" class="error-message">
			<span aria-hidden="true">⚠️</span>
			{errorMessage}
		</p>
	{/if}

	{#if !touched}
		<p class="hint">Choose a username with at least 3 characters</p>
	{/if}
</div>

<style>
	.form-field {
		display: flex;
		flex-direction: column;
		gap: 0.375rem;
	}

	label {
		font-size: 0.875rem;
		font-weight: 500;
		color: #374151;
	}

	.input-wrapper {
		position: relative;
	}

	.input {
		width: 100%;
		padding: 0.625rem 1rem;
		font-size: 1rem;
		border: 2px solid;
		border-radius: 8px;
		outline: none;
		transition: all 0.2s ease;
	}

	.input.neutral {
		border-color: #d1d5db;
		background-color: white;
	}

	.input.neutral:focus {
		border-color: #3b82f6;
		box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.2);
	}

	.input.error {
		border-color: #ef4444;
		background-color: #fef2f2;
		color: #991b1b;
	}

	.input.error:focus {
		box-shadow: 0 0 0 3px rgba(239, 68, 68, 0.2);
	}

	.input.success {
		border-color: #22c55e;
		background-color: #f0fdf4;
	}

	.input.success:focus {
		box-shadow: 0 0 0 3px rgba(34, 197, 94, 0.2);
	}

	.success-icon {
		position: absolute;
		right: 1rem;
		top: 50%;
		transform: translateY(-50%);
		color: #22c55e;
		font-weight: bold;
	}

	.error-message {
		display: flex;
		align-items: center;
		gap: 0.375rem;
		margin: 0;
		font-size: 0.875rem;
		color: #dc2626;
	}

	.hint {
		margin: 0;
		font-size: 0.875rem;
		color: #6b7280;
	}
</style>

Este exemplo demonstra várias práticas importantes:

A validação só é exibida após o usuário ter interagido (touched)
Erros não aparecem enquanto o usuário ainda está digitando (!focused)
Três estados visuais distintos: erro (vermelho), sucesso (verde) e neutro (cinza/azul)
Acessibilidade adequada com aria-invalid e aria-describedby
Um ícone de sucesso oferece reforço positivo
Texto de dica útil antes da interação do usuário

3. Seleção Interativa de Cards

Cards que podem ser selecionados precisam de feedback visual claro. Aqui está um padrão para uma grade de cards selecionáveis:

<script>
	let plans = $state([
		{
			id: 'basic',
			name: 'Basic',
			price: 9,
			features: ['5 projects', '10GB storage', 'Email support']
		},
		{
			id: 'pro',
			name: 'Professional',
			price: 29,
			features: ['Unlimited projects', '100GB storage', 'Priority support', 'API access']
		},
		{
			id: 'enterprise',
			name: 'Enterprise',
			price: 99,
			features: [
				'Everything in Pro',
				'Unlimited storage',
				'Dedicated support',
				'Custom integrations',
				'SLA guarantee'
			]
		}
	])

	let selectedPlan = $state('pro')
</script>

<div class="plan-grid">
	{#each plans as plan}
		{@const isSelected = selectedPlan === plan.id}
		<button
			class={['plan-card', isSelected && 'selected']}
			onclick={() => (selectedPlan = plan.id)}
			aria-pressed={isSelected}
		>
			{#if isSelected}
				<span class="selected-badge">Selected</span>
			{/if}

			<h3 class={['plan-name', isSelected && 'selected']}>{plan.name}</h3>

			<p class="plan-price">
				<span class={['price-amount', isSelected && 'selected']}>${plan.price}</span>
				<span class="price-period">/month</span>
			</p>

			<ul class="feature-list">
				{#each plan.features as feature}
					<li class="feature-item">
						<span class={['check-icon', isSelected && 'selected']}>✓</span>
						{feature}
					</li>
				{/each}
			</ul>
		</button>
	{/each}
</div>

<style>
	.plan-grid {
		display: grid;
		grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
		gap: 1.5rem;
		padding: 1rem;
	}

	.plan-card {
		position: relative;
		padding: 2rem;
		background: white;
		border: 2px solid #e5e7eb;
		border-radius: 16px;
		text-align: left;
		cursor: pointer;
		transition: all 0.2s ease;
	}

	.plan-card:hover {
		border-color: #d1d5db;
		box-shadow: 0 10px 25px -5px rgb(0 0 0 / 0.1);
		transform: translateY(-2px);
	}

	.plan-card.selected {
		border-color: #3b82f6;
		background-color: #eff6ff;
		box-shadow:
			0 0 0 3px rgba(59, 130, 246, 0.2),
			0 10px 25px -5px rgb(0 0 0 / 0.1);
		transform: scale(1.02);
	}

	.selected-badge {
		position: absolute;
		top: -0.75rem;
		right: -0.5rem;
		padding: 0.25rem 0.75rem;
		background: #3b82f6;
		color: white;
		font-size: 0.75rem;
		font-weight: 600;
		border-radius: 9999px;
	}

	.plan-name {
		margin: 0 0 0.5rem;
		font-size: 1.25rem;
		color: #111827;
	}

	.plan-name.selected {
		color: #1d4ed8;
	}

	.plan-price {
		margin: 0 0 1.5rem;
	}

	.price-amount {
		font-size: 2rem;
		font-weight: 700;
		color: #111827;
	}

	.price-amount.selected {
		color: #2563eb;
	}

	.price-period {
		font-size: 1rem;
		color: #6b7280;
	}

	.feature-list {
		list-style: none;
		margin: 0;
		padding: 0;
		display: flex;
		flex-direction: column;
		gap: 0.625rem;
	}

	.feature-item {
		display: flex;
		align-items: center;
		gap: 0.5rem;
		font-size: 0.9375rem;
		color: #4b5563;
	}

	.check-icon {
		color: #9ca3af;
		font-weight: bold;
	}

	.check-icon.selected {
		color: #3b82f6;
	}
</style>

Este padrão demonstra:

Cards são botões para garantir acessibilidade adequada via teclado
O estado selecionado usa cor, sombra e escala sutil para dar ênfase
Cards não selecionados possuem estados de hover que sugerem interatividade
O badge "Selecionado" torna a seleção atual inconfundível
aria-pressed comunica o estado de seleção para leitores de tela

4. Alternância de Tema (Modo Claro/Escuro)

A alternância de tema é um padrão comum que demonstra bem o gerenciamento dinâmico de classes:

<script>
	let isDark = $state(false)
</script>

<div class={['app-container', isDark && 'dark-theme']}>
	<header class="header">
		<h1>My Application</h1>
		<button class="theme-toggle" onclick={() => (isDark = !isDark)}>
			<span class="toggle-icon">{isDark ? '☀️' : '🌙'}</span>
			<span class="toggle-text">{isDark ? 'Light Mode' : 'Dark Mode'}</span>
		</button>
	</header>

	<main class="content">
		<p>
			This content adapts to the current theme. The background, text colors, and other elements all
			respond to the theme state.
		</p>

		<div class="card">
			<h2>Feature Card</h2>
			<p>Cards and other components inherit the theme styling automatically.</p>
		</div>
	</main>
</div>

<style>
	.app-container {
		min-height: 100vh;
		background-color: #ffffff;
		color: #1f2937;
		transition: all 0.3s ease;
	}

	.app-container.dark-theme {
		background-color: #111827;
		color: #f3f4f6;
	}

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

	.dark-theme .header {
		border-bottom-color: #374151;
	}

	h1 {
		margin: 0;
		font-size: 1.5rem;
	}

	.theme-toggle {
		display: flex;
		align-items: center;
		gap: 0.5rem;
		padding: 0.5rem 1rem;
		background-color: #f3f4f6;
		color: #374151;
		border: none;
		border-radius: 8px;
		cursor: pointer;
		transition: all 0.2s ease;
	}

	.dark-theme .theme-toggle {
		background-color: #374151;
		color: #f3f4f6;
	}

	.theme-toggle:hover {
		background-color: #e5e7eb;
	}

	.dark-theme .theme-toggle:hover {
		background-color: #4b5563;
	}

	.toggle-icon {
		font-size: 1.25rem;
	}

	.toggle-text {
		font-size: 0.875rem;
		font-weight: 500;
	}

	.content {
		max-width: 800px;
		margin: 0 auto;
		padding: 2rem;
	}

	.card {
		margin-top: 2rem;
		padding: 1.5rem;
		background-color: #f9fafb;
		border: 1px solid #e5e7eb;
		border-radius: 12px;
	}

	.dark-theme .card {
		background-color: #1f2937;
		border-color: #374151;
	}

	.card h2 {
		margin: 0 0 0.5rem;
		font-size: 1.125rem;
	}

	.card p {
		margin: 0;
		color: #6b7280;
	}

	.dark-theme .card p {
		color: #9ca3af;
	}
</style>

Este exemplo mostra como uma única variável de estado (isDark) pode controlar a estilização em uma página inteira. O contêiner pai recebe a classe dark-theme, e os elementos filhos podem usar o padrão de seletor .dark-theme .element para adaptar sua estilização.

Dificuldades Comuns e Como Resolvê-las

Mesmo desenvolvedores experientes encontram problemas com classes dinâmicas. Aqui estão os problemas mais comuns e suas soluções.

1. Concatenação de Strings Criando Espaços ou "false"

Quando os desenvolvedores tentam classes dinâmicas pela primeira vez, costumam recorrer à concatenação de strings, o que gera problemas:

<script>
	let isActive = $state(false)
	let isLarge = $state(true)
</script>

<!-- AVOID: Extra spaces in the class string -->
<div class="base {isActive ? 'active' : ''} {isLarge ? 'large' : ''}">
	<!-- Result: "base  large" - notice the double space! -->
</div>

<!-- AVOID: "false" becomes a literal class name -->
<div class={'base ' + (isActive && 'active')}>
	<!-- Result: "base false" - oops! -->
</div>

O primeiro exemplo deixa uma string vazia no meio, criando um espaço duplo. O segundo exemplo é pior: quando isActive é falso, o operador && retorna false, que é concatenado como a string literal "false".

A solução é simples: use arrays em vez disso.

<!-- PREFERRED: Arrays filter out falsy values automatically -->
<div class={['base', isActive && 'active', isLarge && 'large']}>
	<!-- Result: "base large" - clean! -->
</div>

<!-- PREFERRED: Objects work too -->
<div class={{ base: true, active: isActive, large: isLarge }}>
	<!-- Result: "base large" -->
</div>

Tanto arrays quanto objetos lidam com valores falsos de forma adequada — eles simplesmente são omitidos da string final de classes.

2. Estilos com Escopo Não Sendo Aplicados a Classes Dinâmicas

O Svelte aplica escopo aos estilos do seu componente adicionando atributos de classe únicos. Mas se um nome de classe aparecer apenas de forma dinâmica, o Svelte pode não incluí-lo nos estilos com escopo:

<script>
	let isHighlighted = $state(true)
</script>

<div class={{ highlight: isHighlighted }}>This text should have a yellow background...</div>

<style>
	.highlight {
		background-color: yellow;
	}
</style>

Se o compilador do Svelte não encontrar .highlight usado como classe estática em nenhum lugar, ele pode não incluir a versão com escopo desse estilo. Este é um caso extremo, mas pode ser confuso quando acontece.

Solução 1: Use :global() para classes dinâmicas

<style>
	:global(.highlight) {
		background-color: yellow;
	}
</style>

Solução 2: Sempre inclua uma referência estática

Como a classe é usada em uma expressão de objeto/array, o Svelte moderno deve detectá-la. Mas se você estiver com problemas, pode garantir que a classe seja detectada incluindo-a estaticamente em algum lugar (mesmo em uma condição sempre falsa).

3. TypeScript Reclamando da Prop `class`

O TypeScript não gosta de usar class como nome de prop, pois é uma palavra reservada:

<script lang="ts">
	// TypeScript might complain about this
	let { class: className } = $props()
</script>

Solução: Use o tipo ClassValue de svelte/elements

<script lang="ts">
	import type { ClassValue } from 'svelte/elements'

	interface Props {
		class?: ClassValue
		// other props...
	}

	let { class: className, ...rest }: Props = $props()
</script>

<div class={['base-class', className]}>Fully typed!</div>

O tipo ClassValue representa corretamente todos os valores possíveis que o tratamento de classes do Svelte aceita: strings, objetos, arrays e combinações aninhadas.

4. Problemas de Reatividade com Objetos de Classes

Se você estiver armazenando suas condições de classe em uma variável de objeto (em vez de inline), pode encontrar problemas de reatividade:

<script>
	// AVOID: Mutating object properties directly
	let classes = { active: false }

	function toggle() {
		classes.active = !classes.active // Might not trigger update!
	}
</script>

<div class={classes}>Content</div>

Solução: Use $state para objetos reativos

<script>
	// PREFERRED: Use $state for the object
	let classState = $state({ active: false })

	function toggle() {
		classState.active = !classState.active // Works with $state!
	}
</script>

<div class={{ active: classState.active }}>Content</div>

<!-- Or even simpler, use a boolean state -->
<script>
	let isActive = $state(false)
</script>

<div class={{ active: isActive }}>Content</div>

Usar $state garante que o Svelte rastreie as alterações nas propriedades do objeto e atualize o DOM adequadamente.

Considerações de Performance

Embora o tratamento de classes do Svelte já seja altamente otimizado, entender as implicações de performance ajuda a escrever um código melhor.

Extraia Condições Complexas para $derived

Quando você tem lógica complexa determinando classes, extraia-a para $derived em vez de calculá-la inline:

<script>
	let items = $state([])
	let filter = $state('')

	// AVOID: This complex expression runs on every render
	// class={{ 'has-results': items.filter(i => i.name.includes(filter)).length > 0 }}

	// PREFERRED: This only recalculates when items or filter change
	let hasResults = $derived(items.some((i) => i.name.includes(filter)))
</script>

<div class={{ 'has-results': hasResults, 'no-results': !hasResults }}>
	{hasResults ? 'Found items!' : 'No items match your filter'}
</div>

<style>
	.has-results {
		background-color: #f0fdf4;
		border-color: #86efac;
	}

	.no-results {
		background-color: #fef2f2;
		border-color: #fca5a5;
	}
</style>

O valor $derived é armazenado em cache e só é recalculado quando suas dependências mudam. Expressões inline no atributo de classe são recalculadas a cada renderização, mesmo que as entradas não tenham mudado.

Defina Mapeamentos de Classes Estáticas Fora do Template

Se você tiver um conjunto fixo de variantes ou estados, defina os mapeamentos de classes como uma constante:

<script>
	let variant = $state('primary')
	let size = $state('md')

	// Define mappings once, outside the reactive scope
	const variantClasses = {
		primary: 'variant-primary',
		secondary: 'variant-secondary',
		ghost: 'variant-ghost',
		danger: 'variant-danger'
	}

	const sizeClasses = {
		sm: 'size-sm',
		md: 'size-md',
		lg: 'size-lg'
	}
</script>

<button class={['btn', variantClasses[variant], sizeClasses[size]]}> Click me </button>

<style>
	.btn {
		border: none;
		border-radius: 6px;
		font-weight: 500;
		cursor: pointer;
	}

	.variant-primary {
		background-color: #3b82f6;
		color: white;
	}

	.variant-secondary {
		background-color: #e5e7eb;
		color: #374151;
	}

	.variant-ghost {
		background-color: transparent;
		border: 2px solid #e5e7eb;
		color: #374151;
	}

	.variant-danger {
		background-color: #ef4444;
		color: white;
	}

	.size-sm {
		padding: 0.375rem 0.75rem;
		font-size: 0.875rem;
	}

	.size-md {
		padding: 0.5rem 1rem;
		font-size: 1rem;
	}

	.size-lg {
		padding: 0.75rem 1.5rem;
		font-size: 1.125rem;
	}
</style>

Esses objetos constantes são criados uma vez quando o componente inicializa, não a cada renderização. Também é mais fácil de manter—todas as definições de variantes ficam em um único lugar.

Quando o Desempenho Não Importa (Na Maioria das Vezes)

Para a grande maioria das aplicações, as diferenças de desempenho entre as várias abordagens de manipulação de classes são completamente insignificantes. O compilador do Svelte é notavelmente eficiente, e o clsx (que processa objetos/arrays) é altamente otimizado.

Concentre-se em:

Legibilidade: Você consegue entender essa lógica de classes de relance?
Manutenibilidade: É fácil adicionar uma nova variante ou estado?
Correção: Ela produz as classes corretas em todas as situações?

Otimize para desempenho apenas se você tiver medido um problema. Otimização prematura do tratamento de classes quase nunca vale a troca pela clareza do código.

Resumo de Boas Práticas

Após cobrir todos os detalhes, aqui estão as práticas principais para lembrar:

Use a sintaxe de objeto/array para novo código. A diretiva class: é legada—não há razão para usá-la em novos projetos Svelte 5.
Escolha a sintaxe certa para a situação. Objetos são ótimos para alternâncias booleanas (class={{ active: isActive }}). Arrays são ótimos para combinar múltiplas fontes e grupos condicionais (class={[baseClasses, variant && variantClass]}).
Agrupe classes relacionadas sob condições únicas. Quando um estado visual requer múltiplas classes, coloque-as todas em uma string: 'loading pulse': isLoading.
Coloque as classes do consumidor por último nos arrays do componente. Isso permite que os usuários adicionem estilos extras: class={['base-styles', className]}.
Tipar suas props de classe no TypeScript. Importe ClassValue de svelte/elements para tipagem adequada.
Extraia condições complexas para $derived. Mantenha seus templates limpos e sua lógica eficiente.
Seja consistente dentro da sua base de código. Escolha padrões que funcionem para sua equipe e mantenha-os.
Não se esqueça da acessibilidade. Classes dinâmicas frequentemente estão vinculadas a estados—certifique-se de que esse estado também seja comunicado às tecnologias assistivas via atributos ARIA.
Use propriedades CSS customizadas para tematização. Ao construir alternadores de tema, variáveis CSS podem simplificar significativamente a lógica de classes.
Teste sua lógica de classes. Especialmente para componentes com muitas variantes, verifique se todas as combinações produzem os estilos esperados.

Referência Rápida

Aqui está uma referência útil para todos os padrões de sintaxe de classes:

<!-- Component class props (TypeScript) -->
<script lang="ts">
	import type { ClassValue } from 'svelte/elements'
	let { class: className }: { class?: ClassValue } = $props()
</script>

<!-- Static classes (always applied) -->
<div class="card rounded shadow">Always these classes</div>

<!-- Dynamic string from variable -->
<div class={currentTheme}>Class from variable</div>

<!-- Object syntax: keys are classes, values are conditions -->
<div class={{ active: isActive, disabled: isDisabled }}>Truthy values get applied</div>

<!-- Object with multi-class keys -->
<div class={{ 'loading pulse': isLoading }}>Multiple classes, one condition</div>

<!-- Array syntax: truthy values are combined -->
<div class={['base', isActive && 'active', size === 'lg' && 'large']}>
	Falsy values are filtered out
</div>

<!-- Nested arrays and objects -->
<div class={[baseClasses, { highlight: isHighlighted }, variant && variantClass]}>
	Everything gets flattened
</div>

<!-- Ternary for either/or classes -->
<div class={[isOpen ? 'expanded' : 'collapsed']}>One or the other</div>

<!-- Combining static and dynamic -->
<div class={['always-applied', sometimes && 'conditional']}>Mix freely</div>

<!-- Computed class names -->
<div class={{ [`theme-${theme}`]: true, [`size-${size}`]: true }}>Dynamic class names</div>
<div class={['component-base', className]}>Consumer classes merged</div>

Conclusão

O gerenciamento dinâmico de classes é um daqueles padrões que você usará constantemente no desenvolvimento com Svelte. A abordagem declarativa—descrever o que deve ser verdadeiro em vez de manipular o DOM imperativamente—leva a um código mais limpo e fácil de manter. Com a sintaxe de objeto e array, você tem as ferramentas para lidar com tudo, desde alternâncias simples até sistemas de design complexos com múltiplas variantes.

O tratamento de classes do Svelte transforma o que seria concatenação de strings bagunçada e manipulação imperativa do DOM em JavaScript puro em expressões reativas elegantes que se atualizam automaticamente quando o estado muda.

A evolução da sintaxe de diretiva class: para as novas formas literais de array e objeto representa o compromisso do Svelte 5 em aproveitar recursos modernos do JavaScript para uma melhor experiência do desenvolvedor. Ao entender o comportamento de achatamento, dominar padrões condicionais e utilizar tipos ClassValue para APIs de componentes, você pode construir sistemas de design que são ao mesmo tempo flexíveis e type-safe.

Seja implementando alternâncias simples ou orquestrando sistemas de variantes complexos com dezenas de classes condicionais, o gerenciamento declarativo de classes do Svelte mantém seu código legível e seus componentes fáceis de manter.

Principais Conclusões

A sintaxe de objeto permite a alternância declarativa de classes com class={{ active: isActive, disabled: !enabled }}, onde valores truthy incluem a chave como nome de classe
A sintaxe de array suporta classes estáticas e condicionais combinadas via class={['base-class', condition && 'conditional-class']} com filtragem automática de valores falsy
Arrays achatam automaticamente estruturas aninhadas - class={[baseClasses, [variantClasses, conditionalClasses]]} se torna uma única string de classes separadas por espaço
A avaliação de curto-circuito fornece condicionais inline usando && para "aplicar se verdadeiro" e operadores ternários para seleção de classe "um ou outro"
Props de classe em componentes usam o tipo ClassValue - let { class: className }: { class?: ClassValue } = $props() aceita strings, arrays, objetos ou combinações aninhadas
A mesclagem de classes segue regras de especificidade - a especificidade CSS determina quais estilos se aplicam quando múltiplas classes definem a mesma propriedade, não a ordem no Svelte
$derived permite classes computadas complexas para lógica com múltiplas condições: let classes = $derived({ active, disabled, [variantClass]: true })
Sintaxe de template literal para nomes de classes dinâmicos - class={{ [`theme-${theme}`]: true }} gera nomes de classes a partir de valores em tempo de execução

Veja Também

Documentação Oficial do Svelte 5 - class:
Especificidade CSS - Entendendo como estilos de classes conflitantes são resolvidos
$derived - Valores computados reativos para lógica de classes complexa
$props() - Sistema de props de componente para manipulação de props de classe
TypeScript com Svelte - Definições de valores de classe com type-safety
Diretiva style: - Estilos inline dinâmicos como alternativa às classes
CSS Modules - CSS com escopo como abordagem alternativa de estilização
Tailwind CSS com Svelte - Integração de framework CSS utilitário

Estilização Dinâmica com o Atributo class