Estilizado Dinámico con el Atributo `class`

Toda interfaz interactiva necesita estilizado dinámico. Piensa en las experiencias que encuentras a diario: un enlace de navegación que se resalta cuando estás en esa página, un botón que se atenúa mientras se envía un formulario, un campo de entrada que se vuelve rojo cuando falla la validación, o un interruptor de tema que alterna entre los modos claro y oscuro. Todos estos patrones comparten una necesidad común: agregar y remover clases CSS según el estado actual de tu aplicación.

Si has trabajado con JavaScript puro, sabes que esto puede volverse complicado rápidamente. Terminas con llamadas a classList.add() y classList.remove() dispersas por todo tu código, intentando mantener el DOM sincronizado con tus datos. Si te olvidas de una actualización, tu interfaz queda desincronizada. Svelte elimina esta complejidad por completo al permitirte describir qué clases deben aplicarse cuándo — y el framework se encarga del resto.

Svelte 5 ofrece dos enfoques para la gestión dinámica de clases. El primero es el atributo class mejorado, que incorporó soporte para objetos y arreglos en Svelte 5.16. Este es el enfoque moderno y recomendado que maneja todo, desde simples alternancias hasta lógica compleja de múltiples clases. El segundo es la directiva class:, que era la forma original de aplicar clases condicionalmente en versiones anteriores de Svelte.

Nota importante: La directiva class: todavía funciona perfectamente bien, pero ahora se considera legacy. La encontrarás en tutoriales más antiguos, publicaciones de blog y bases de código, por lo que vale la pena entenderla. Sin embargo, para cualquier código nuevo que escribas, la sintaxis de objeto/arreglo en el atributo class es más poderosa, más composable y el enfoque oficialmente recomendado.

Este tutorial te guiará a través de ambos enfoques de forma integral. Comenzaremos con los fundamentos, avanzaremos hacia patrones complejos del mundo real y resolveremos los problemas más comunes que encuentran los desarrolladores. Al final, tendrás total confianza para gestionar clases CSS dinámicamente en cualquier aplicación Svelte 5.

El Problema: Por Qué Importan las Clases Dinámicas

Antes de adentrarnos en la sintaxis de Svelte, entendamos por qué la gestión dinámica de clases es un desafío tan común y por qué el enfoque de Svelte es mucho mejor que lo que podrías estar acostumbrado.

El Enfoque Tradicional de JavaScript

Imagina que estás construyendo un botón de envío que necesita mostrar diferentes estados visuales: un estado "listo" cuando el usuario puede hacer clic en él, un estado "cargando" mientras el formulario se está enviando, y un estado "deshabilitado" cuando el formulario no es válido. En JavaScript puro, podrías escribir algo así:

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

Este enfoque tiene varios problemas que se vuelven más dolorosos a medida que crece tu aplicación:

Lógica dispersa: Tu código de gestión de clases vive en JavaScript, completamente separado de tu HTML. Para entender cómo se estiliza un elemento, debes buscar en múltiples archivos y rastrear llamadas a funciones.
Sincronización manual: Cada vez que cambia tu estado, debes recordar llamar a la función de actualización. Si olvidas una llamada, tu interfaz muestra el estado incorrecto. Esta es una fuente constante de errores.
Mantenimiento propenso a errores: ¿Qué sucede cuando agregas un cuarto estado? Necesitas encontrar cada lugar que llama a updateButtonState, actualizar la firma de la función y asegurarte de que la nueva clase se elimine en el paso de limpieza. Si te falta alguno, tendrás errores sutiles.
Poca legibilidad: Al ver el HTML solo, no tienes idea de qué clases podrían aplicarse dinámicamente. La conexión entre tus datos y tu estilizado es invisible.

La Solución Declarativa de Svelte

Ahora veamos cómo Svelte maneja exactamente el mismo requerimiento. En lugar de decirle imperativamente al DOM qué hacer, describes declarativamente qué debería ser verdad según tu 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>

¡Mira qué mucho más limpio es esto! La relación entre el estado y el estilizado es completamente clara, justo ahí en la plantilla donde puedes verla. Cuando isLoading es true, el botón recibe la clase loading. Cuando tanto isLoading como isDisabled son false, recibe la clase ready. No hay ninguna función que llamar, ninguna sincronización que gestionar—Svelte observa tu estado reactivo y actualiza el DOM automáticamente cada vez que algo cambia.

Este enfoque declarativo significa que puedes concentrarte en qué quieres, no en cómo lograrlo. Tu código se vuelve más corto, más legible y mucho menos propenso a errores. Ahora aprendamos cómo usar este poder de manera efectiva.

El Atributo `class`: Tu Fundamento

El atributo class en Svelte funciona exactamente como esperarías en HTML, con algunas mejoras poderosas. Comencemos con los conceptos básicos y avancemos hacia patrones más sofisticados.

Clases Estáticas: Igual que en HTML

En su forma más simple, el atributo class funciona exactamente como en HTML regular. Si solo necesitas clases estáticas que nunca cambian, escríbelas como una cadena de texto simple:

<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 especial aquí — estas clases se aplican cuando el componente se monta y nunca cambian. Pero claro, no es por eso que estás leyendo este tutorial. Hagamos las cosas dinámicas.

Clases Dinámicas con Expresiones

Cuando envuelves el valor de class entre llaves {}, puedes usar cualquier expresión de JavaScript. El caso más simple es usar una variable:

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

Cuando currentSize es 'large', el div obtiene class="large". Si luego cambias currentSize a 'small', Svelte actualiza automáticamente el DOM a class="small". No se requiere intervención manual.

También puedes usar expresiones más complejas, como operadores ternarios, para elegir entre dos posibles clases:

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

Cada vez que haces clic en el botón, isExpanded alterna entre true y false, y la clase del div se actualiza en consecuencia. El operador ternario (condición ? valorSiVerdadero : valorSiFalso) es perfecto cuando necesitas elegir entre exactamente dos clases.

Entendiendo los Valores Falsy

Antes de continuar, es importante entender cómo Svelte maneja los valores "falsy" en el atributo class. En JavaScript, ciertos valores se consideran "falsy" — se evalúan como false en contextos booleanos. Estos incluyen false, 0, '' (cadena vacía), null, undefined y NaN.

Svelte los maneja de manera diferente dependiendo de cuáles son:

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

Este comportamiento existe por razones históricas, pero es importante tenerlo en cuenta. Si tu expresión podría evaluarse como false u otro valor falsy, necesitas manejar ese caso explícitamente — o mejor aún, usa la sintaxis de objeto/arreglo que aprenderemos a continuación, que maneja los valores falsy de manera elegante.

Mirando hacia adelante: Una versión futura de Svelte hará que todos los valores falsy omitan el atributo class por completo, haciendo el comportamiento más consistente. Pero por ahora, null y undefined son tus opciones más seguras cuando quieres omitir el atributo condicionalmente.

Sintaxis de Objeto: Control Fino de Clases

A partir de Svelte 5.16, el atributo class incorporó la capacidad de aceptar objetos. Esto es un cambio radical para la gestión dinámica de clases y es el enfoque que deberías usar en la mayoría de las situaciones. Internamente, Svelte usa la popular biblioteca clsx para procesar estos objetos.

Cómo Funciona la Sintaxis de Objeto

La idea básica es simple: pasas un objeto donde las claves son nombres de clases y los valores son booleanos (o expresiones que se evalúan como valores truthy/falsy). Si el valor es truthy, la clase se aplica. Si es falsy, la clase no se aplica.

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

Analicemos lo que está sucediendo aquí:

active: isActive — Como isActive es true, la clase active se aplica
disabled: isDisabled — Como isDisabled es false, la clase disabled NO se aplica
highlighted: isHighlighted — Como isHighlighted es true, la clase highlighted se aplica

El HTML resultante es <div class="active highlighted">. Si luego estableces isDisabled = true y isHighlighted = false, Svelte actualiza automáticamente el DOM a <div class="active disabled">.

Este patrón es increíblemente poderoso porque cada clase es controlada de forma independiente por su propia condición. No tienes que preocuparte por eliminar clases antiguas o gestionar transiciones de estado — simplemente describes qué debería ser verdad en este momento.

Abreviatura de Propiedades de JavaScript

Cuando el nombre de tu variable coincide con el nombre de la clase que deseas aplicar, la abreviatura de propiedades de JavaScript hace las cosas aún más limpias:

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

Esta abreviatura es simplemente la sintaxis de objeto estándar de JavaScript — { active } es exactamente lo mismo que { active: active }. Es algo pequeño, pero hace que tu código sea más limpio y reduce la repetición.

Usar Expresiones como Valores

Los valores en tu objeto no tienen que ser simples variables booleanas. Puedes usar cualquier expresión que se evalúe como un valor truthy o 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 clave-valor se evalúa de forma independiente. La clase has-items se aplica porque itemCount > 0 es true (5 > 0). La clase is-admin se aplica porque userRole === 'admin' es true. La clase has-error NO se aplica porque errorMessage.length > 0 es false (la cadena vacía tiene longitud 0).

Nombres de Clases Dinámicos con Claves Calculadas

A veces necesitas que el nombre de la clase en sí sea dinámico, no solo si se aplica o no. Puedes usar la sintaxis de propiedades calculadas de JavaScript (corchetes) para crear nombres de clases a partir de expresiones:

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

Los corchetes le indican a JavaScript que evalúe la expresión dentro de ellos y use el resultado como la clave de la propiedad. Entonces [`theme-${theme}`] se convierte en 'theme-dark' cuando theme es 'dark'. El valor true significa "aplicar siempre esta clase."

Esto es particularmente útil cuando trabajas con un sistema de diseño que usa convenciones de nomenclatura como variant-primary, size-lg o theme-dark.

Aplicar Múltiples Clases con una Sola Condición

Una de las características más poderosas de la sintaxis de objeto es la capacidad de alternar múltiples clases con una sola condición. Simplemente coloca todos los nombres de clases en la clave, separados por espacios:

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

Cuando isLoading es true, ambas clases (loading y pulse) se aplican juntas. Cuando se vuelve false, ambas se eliminan juntas. Esto facilita agrupar estilos relacionados — la apariencia visual y la animación van de la mano.

Piénsalo: con el enfoque antiguo, necesitarías lógica separada para cada clase. Con la sintaxis de objeto, las clases relacionadas se agrupan por su condición, dejando tu intención completamente clara.

Sintaxis de Array: Combinando Múltiples Fuentes de Clases

Si bien la sintaxis de objeto es ideal para alternar valores booleanos, la sintaxis de array brilla cuando necesitas combinar múltiples fuentes de clases o usar lógica condicional más compleja. Al igual que los objetos, los arrays son procesados por clsx y todos los valores falsy son filtrados automáticamente.

Cómo Funciona la Sintaxis de Array

Con la sintaxis de array, proporcionas un array de valores. Cada valor puede ser una cadena (que siempre se incluye) o una expresión que evalúa a una cadena (incluida) o un valor falsy (excluido):

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

Analicemos cada elemento:

'btn' — Una cadena simple, siempre incluida
'rounded' — Otra cadena simple, siempre incluida
isPrimary && 'primary' — isPrimary es true, por lo que evalúa a 'primary' (incluida)
isLarge && 'large' — isLarge es false, por lo que evalúa a false (excluida)
isDisabled && 'disabled' — isDisabled es false, por lo que evalúa a false (excluida)

La magia está en cómo funciona el operador && de JavaScript: si el lado izquierdo es falsy, devuelve el lado izquierdo (que queda filtrado). Si el lado izquierdo es truthy, devuelve el lado derecho (el nombre de la clase). Este patrón es tan común en React y Svelte que vale la pena memorizarlo.

Grupos de Clases Condicionales con Operadores Ternarios

A veces necesitas elegir entre dos conjuntos de clases diferentes, no solo incluir o excluir una sola clase. Los operadores ternarios funcionan perfectamente dentro de los 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>

La clase base (status-card) siempre se aplica. Luego, dependiendo del valor de status, se agregan diferentes clases de estilo. Esto crea un mapeo limpio entre el estado y la presentación.

Para mayor legibilidad con múltiples estados, puede que prefieras múltiples condiciones:

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

Ambos enfoques funcionan; elige el que sea más claro para tu caso específico. Cuando los estados son mutuamente excluyentes (solo uno puede ser verdadero a la vez), el segundo enfoque con condiciones separadas suele ser más legible.

Anidando Arrays y Objetos

Una de las características más poderosas de clsx (y por lo tanto del manejo de clases de Svelte) es que los arrays pueden contener otros arrays e incluso objetos. Todo se aplana y procesa correctamente:

<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 ejemplo demuestra varios conceptos trabajando juntos:

Arrays de clases reutilizables (cardBase, interactiveStyles) que pueden compartirse entre componentes
Un objeto embebido para clases basadas en alternancia
Una expresión condicional para clases específicas de variante

Todo se aplana en una sola cadena de clases. Esta composabilidad es increíblemente poderosa para construir sistemas de diseño donde quieres compartir estilos base mientras permites la personalización.

Composición de Clases en Componentes

Al construir componentes reutilizables, a menudo querrás permitir que los consumidores agreguen sus propias clases mientras preservan el estilo base del componente. Aquí es donde el manejo de clases de Svelte 5 realmente brilla.

El Desafío: Aceptar Clases Externas

Imagina que estás construyendo un componente Button. Tiene sus propios estilos, pero quieres que los usuarios puedan agregar clases adicionales para espaciado, tamaño o estilos personalizados sin modificar el componente en sí. Así es como hacerlo:

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

Observa algunas cosas importantes:

Renombramos la prop: Usamos class: className porque class es una palabra reservada en JavaScript. Esto desestructura la prop class en una variable llamada className.
Ponemos className al final: ¡Esto es intencional! Al poner las clases del usuario al final, les permitimos agregar estilos adicionales que funcionan junto con nuestros estilos base.
El componente define sus estilos base: El botón siempre tiene la clase btn. Estos son los estilos base no negociables.
Las clases de variante son condicionales: Dependiendo de la prop variant, se aplican diferentes clases de color/estilo.

Ahora los consumidores pueden usar el componente así:

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

Una de las cosas hermosas del manejo de clases de Svelte es que los consumidores pueden pasar clases como cadenas, objetos o arrays—lo que sea más conveniente para su 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>

Debido a que todo pasa por clsx, todos estos formatos funcionan sin problemas. Tu componente no necesita hacer nada especial—simplemente incluye className en tu array de clases, y Svelte se encarga del resto.

Soporte de TypeScript con ClassValue

Si estás usando TypeScript, querrás tipar correctamente tus props de clase. Svelte 5.19 introdujo el tipo ClassValue específicamente para este 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>

El tipo ClassValue acepta cadenas, objetos, arrays y cualquier combinación anidada de los mismos—exactamente lo que soporta el manejo de clases de Svelte. Esto te brinda seguridad de tipos completa mientras mantienes total flexibilidad.

La Directiva `class:` (Sintaxis Heredada)

Antes de que Svelte 5.16 agregara soporte de objetos y arrays al atributo class, la directiva class: era la única forma de aplicar clases condicionalmente. Si bien todavía funciona perfectamente, ahora se considera sintaxis heredada. Deberías usar la sintaxis de objeto/array para código nuevo, pero entender la directiva es valioso ya que la encontrarás en bases de código antiguas, tutoriales y respuestas de Stack Overflow.

Cómo Funciona la Directiva

La directiva class: sigue el patrón class:name={condition}, donde name es la clase a aplicar y condition es una expresión 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>

Cuando la condición es truthy, la clase se agrega. Cuando es falsy, la clase se elimina. Suficientemente simple, pero observa cómo cada clase necesita su propia directiva. Compara esto con la sintaxis 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>

Ambos producen el mismo resultado, pero la sintaxis de objeto es más compacta y mantiene toda la lógica de clases en un solo lugar.

Sintaxis Abreviada

Cuando el nombre de tu variable coincide exactamente con el nombre de la clase que quieres aplicar, puedes usar una forma abreviada que omite el 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>

Esto solo funciona cuando el nombre de la variable y el nombre de la clase son idénticos. Es una conveniencia agradable, pero restringe el nombre de tus variables.

Combinando la Directiva con Clases Estáticas

Puedes usar la directiva class: junto con un atributo class regular para clases 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>

Las clases estáticas (card) siempre están presentes. Las clases controladas por la directiva (selected, highlighted) se agregan o eliminan en función de isSelected.

Por Qué la Sintaxis de Objeto/Array es Mejor

La sintaxis de directiva tiene varias limitaciones que la sintaxis moderna resuelve:

Sin condiciones de múltiples clases: No puedes alternar múltiples clases con una sola directiva. Cada clase necesita su propia directiva.
Más verbosa: Cinco clases condicionales significa cinco directivas separadas llenando tu elemento.
No es composable: No puedes combinar fácilmente clases de directiva con clases pasadas como props.
Mezcla dos sintaxis: Usar tanto class="..." como class:name en el mismo elemento puede ser confuso.

La sintaxis de objeto/array resuelve todos estos problemas. Úsala para código nuevo, y considera migrar el código heredado cuando estés realizando otros cambios en esos componentes.

Patrones y Ejemplos del Mundo Real

Veamos algunos ejemplos completos y prácticos que demuestran cómo usar clases dinámicas en aplicaciones reales.

1. Navegación con Estado Activo

Casi todas las aplicaciones necesitan navegación que resalte la página actual. Aquí hay una implementación completa y accesible:

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

Puntos clave en este ejemplo:

Usamos @const para calcular isActive una vez por iteración, manteniendo la plantilla limpia
El atributo aria-current="page" se aplica condicionalmente para accesibilidad
Los elementos activos obtienen un borde inferior visible, texto con color y un fondo sutil
Los elementos inactivos tienen estados hover que previsualizan cómo se verá el estado activo
El ícono está marcado como aria-hidden ya que es decorativo

2. Validación de Formularios con Retroalimentación Visual

Los campos de formulario necesitan comunicar su estado de validación con claridad. Aquí hay un componente de entrada completo con estilos de validación:

<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 ejemplo muestra varias prácticas importantes:

La validación solo se muestra después de que el usuario ha interactuado (touched)
Los errores no parpadean mientras el usuario sigue escribiendo (!focused)
Tres estados visuales distintos: error (rojo), éxito (verde) y neutro (gris/azul)
Accesibilidad adecuada con aria-invalid y aria-describedby
Una marca de verificación de éxito proporciona refuerzo positivo
Texto de ayuda antes de que el usuario interactúe

3. Selección Interactiva de Tarjetas

Las tarjetas que pueden seleccionarse necesitan retroalimentación visual clara. Aquí hay un patrón para una cuadrícula de tarjetas seleccionables:

<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 patrón demuestra:

Las tarjetas son botones para una accesibilidad adecuada con el teclado
El estado seleccionado usa color, sombra y una escala sutil para dar énfasis
Las tarjetas no seleccionadas tienen estados hover que sugieren interactividad
La insignia "Seleccionado" hace que la selección actual sea inconfundible
aria-pressed comunica el estado de selección a los lectores de pantalla

4. Alternador de Tema (Modo Claro/Oscuro)

Un alternador de tema es un patrón común que demuestra bien la gestión dinámica de clases:

<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 ejemplo muestra cómo una sola variable de estado (isDark) puede controlar el estilo de toda una página. El contenedor padre obtiene la clase dark-theme, y los elementos hijos pueden usar el patrón de selector .dark-theme .element para adaptar su estilo.

Problemas Comunes y Cómo Resolverlos

Incluso los desarrolladores con experiencia se encuentran con problemas al usar clases dinámicas. Aquí están los problemas más comunes y sus soluciones.

1. Concatenación de Cadenas que Genera Espacios o "false"

Cuando los desarrolladores prueban por primera vez las clases dinámicas, suelen recurrir a la concatenación de cadenas, lo que genera 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>

El primer ejemplo deja una cadena vacía en el medio, creando un espacio doble. El segundo ejemplo es peor: cuando isActive es false, el operador && devuelve false, que se concatena como la cadena literal "false".

La solución es simple: usa arrays en su lugar.

<!-- 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 los arrays como los objetos manejan los valores falsy de manera elegante: simplemente se omiten de la cadena de clases final.

2. Los Estilos con Ámbito No se Aplican a las Clases Dinámicas

Svelte delimita los estilos de tu componente añadiendo atributos de clase únicos. Pero si un nombre de clase solo aparece dinámicamente, Svelte podría no incluirlo en los estilos con ámbito:

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

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

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

Si el compilador de Svelte no detecta .highlight usado como clase estática en ningún lugar, es posible que no incluya la versión con ámbito de ese estilo. Es un caso extremo, pero puede ser confuso cuando ocurre.

Solución 1: Usa :global() para clases dinámicas

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

Solución 2: Incluye siempre una referencia estática

Como la clase se usa en una expresión de objeto/array, Svelte moderno debería detectarla. Pero si tienes problemas, puedes asegurarte de que la clase sea detectada incluyéndola estáticamente en algún lugar (incluso en una condición que siempre sea falsa).

3. TypeScript se Queja de la Prop `class`

TypeScript no se lleva bien con el uso de class como nombre de prop, ya que es una palabra reservada:

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

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

El tipo ClassValue representa correctamente todos los valores posibles que acepta el manejo de clases de Svelte: cadenas, objetos, arrays y combinaciones anidadas.

4. Problemas de Reactividad con Objetos de Clases

Si almacenas las condiciones de tus clases en una variable de objeto (en lugar de hacerlo de forma inline), podrías encontrarte con problemas de reactividad:

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

Solución: Usa $state para objetos reactivos

<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 garantiza que Svelte rastree los cambios en las propiedades del objeto y actualice el DOM en consecuencia.

Consideraciones de Rendimiento

Si bien el manejo de clases de Svelte ya está altamente optimizado, entender las implicaciones de rendimiento te ayuda a escribir mejor código.

Extrae las Condiciones Complejas a $derived

Cuando tienes lógica compleja que determina las clases, extráela a $derived en lugar de calcularla de forma 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>

El valor $derived se almacena en caché y solo se recalcula cuando cambian sus dependencias. Las expresiones inline en el atributo class se recalculan en cada renderizado, incluso si las entradas no han cambiado.

Define Mapeos de Clases Estáticas Fuera de la Plantilla

Si tienes un conjunto fijo de variantes o estados, define los mapeos de clases como una 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>

Estos objetos constantes se crean una sola vez cuando el componente se inicializa, no en cada renderizado. También es más fácil de mantener: todas las definiciones de variantes están en un solo lugar.

Cuándo el rendimiento no importa (la mayor parte del tiempo)

Para la gran mayoría de las aplicaciones, las diferencias de rendimiento entre los distintos enfoques para manejar clases son completamente insignificantes. El compilador de Svelte es notablemente eficiente, y clsx (que potencia el procesamiento de objetos/arreglos) está muy optimizado.

Enfócate en:

Legibilidad: ¿Puedes entender esta lógica de clases de un vistazo?
Mantenibilidad: ¿Es fácil agregar una nueva variante o estado?
Corrección: ¿Produce las clases correctas en todas las situaciones?

Solo optimiza para rendimiento si has medido un problema. La optimización prematura del manejo de clases casi nunca vale el costo en claridad del código.

Resumen de buenas prácticas

Después de cubrir todos los detalles, estas son las prácticas clave a recordar:

Usa la sintaxis de objeto/arreglo para código nuevo. La directiva class: es legado — no hay razón para usarla en proyectos nuevos de Svelte 5.
Elige la sintaxis adecuada para cada situación. Los objetos son ideales para alternancias booleanas (class={{ active: isActive }}). Los arreglos son ideales para combinar múltiples fuentes y grupos condicionales (class={[baseClasses, variant && variantClass]}).
Agrupa las clases relacionadas bajo una sola condición. Cuando un estado visual requiere múltiples clases, ponlas todas en una sola cadena: 'loading pulse': isLoading.
Pon las clases del consumidor al final en los arreglos de componentes. Esto permite a los usuarios agregar estilos adicionales: class={['base-styles', className]}.
Tipifica tus props de clase en TypeScript. Importa ClassValue de svelte/elements para un tipado adecuado.
Extrae condiciones complejas a $derived. Mantén tus plantillas limpias y tu lógica eficiente.
Sé consistente dentro de tu base de código. Elige patrones que funcionen para tu equipo y apégate a ellos.
No olvides la accesibilidad. Las clases dinámicas a menudo están vinculadas a un estado — asegúrate de que ese estado también se comunique a las tecnologías de asistencia mediante atributos ARIA.
Usa propiedades personalizadas de CSS para los temas. Al construir selectores de tema, las variables CSS pueden simplificar significativamente tu lógica de clases.
Prueba tu lógica de clases. Especialmente para componentes con muchas variantes, verifica que todas las combinaciones produzcan los estilos esperados.

Referencia rápida

Aquí hay una referencia práctica para todos los patrones de sintaxis de clases:

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

Conclusión

La gestión dinámica de clases es uno de esos patrones que usarás constantemente en el desarrollo con Svelte. El enfoque declarativo — describir qué debe ser verdadero en lugar de manipular el DOM de forma imperativa — lleva a un código más limpio y fácil de mantener. Con la sintaxis de objeto y arreglo, tienes las herramientas para manejar desde alternancia simples hasta sistemas de diseño complejos con múltiples variantes.

El manejo de clases en Svelte transforma lo que sería una concatenación de cadenas desordenada y manipulación imperativa del DOM en JavaScript puro, en expresiones reactivas y elegantes que se actualizan automáticamente cuando el estado cambia.

La evolución de la sintaxis de la directiva class: hacia las nuevas formas de arreglos y literales de objeto representa el compromiso de Svelte 5 de aprovechar las características modernas de JavaScript para una mejor experiencia del desarrollador. Al comprender el comportamiento de aplanamiento, dominar los patrones condicionales y utilizar los tipos ClassValue para las APIs de componentes, puedes construir sistemas de diseño que sean tanto flexibles como seguros en tipos.

Ya sea que estés implementando alternancia simples u orquestando sistemas de variantes complejos con docenas de clases condicionales, la gestión declarativa de clases de Svelte mantiene tu código legible y tus componentes fáciles de mantener.

Conclusiones clave

La sintaxis de objeto permite la alternancia declarativa de clases con class={{ active: isActive, disabled: !enabled }}, donde los valores verdaderos incluyen la clave como nombre de clase
La sintaxis de arreglo admite clases estáticas y condicionales combinadas mediante class={['base-class', condition && 'conditional-class']} con filtrado automático de valores falsy
Los arreglos aplanan automáticamente las estructuras anidadas — class={[baseClasses, [variantClasses, conditionalClasses]]} se convierte en una sola cadena de clases separadas por espacios
La evaluación de cortocircuito provee condicionales en línea usando && para "aplicar si es verdadero" y operadores ternarios para la selección "uno u otro" de clases
Las props de clase de los componentes usan el tipo ClassValue — let { class: className }: { class?: ClassValue } = $props() acepta cadenas, arreglos, objetos o combinaciones anidadas
La fusión de clases sigue las reglas de especificidad — la especificidad de CSS determina qué estilos se aplican cuando múltiples clases definen la misma propiedad, no el orden en Svelte
$derived permite clases computadas complejas para lógica de múltiples condiciones: let classes = $derived({ active, disabled, [variantClass]: true })
La sintaxis de literales de plantilla para nombres de clase dinámicos — class={{ [`theme-${theme}`]: true }} genera nombres de clase a partir de valores en tiempo de ejecución

Ver también

Documentación oficial de Svelte 5 - class:
Especificidad CSS - Comprender cómo se resuelven los estilos de clases en conflicto
$derived - Valores computados reactivos para lógica de clases compleja
$props() - Sistema de props de componentes para el manejo de props de clase
TypeScript con Svelte - Definiciones de valores de clase con seguridad de tipos
Directiva style: - Estilos en línea dinámicos como alternativa a las clases
CSS Modules - CSS con alcance limitado como enfoque alternativo de estilos
Tailwind CSS con Svelte - Integración del framework CSS de utilidad primero

Estilizado Dinámico con el Atributo class