Estilos dinámicos con el atributo `class`

Toda interfaz interactiva necesita estilos dinámicos. 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 oscurece 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 cambia entre modos claro y oscuro. Todos estos patrones comparten una necesidad común: agregar y eliminar 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 omites 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 obtuvo soporte poderoso para objetos y arrays en Svelte 5.16. Este es el enfoque moderno y recomendado que maneja todo, desde simples interruptores 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: sigue funcionando perfectamente, pero ahora se considera legado. La encontrarás en tutoriales 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/array en el atributo class es más poderosa, más componible y el enfoque oficialmente recomendado.

Este tutorial te guiará a través de ambos enfoques de manera exhaustiva. 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 plena 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 quizás estás 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, un estado "cargando" mientras se envía el formulario, y un estado "deshabilitado" cuando el formulario no es válido. En JavaScript puro, podrías escribir algo como esto:

// 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: El código de gestión de clases vive en JavaScript, completamente separado de tu HTML. Para entender cómo se estiliza un elemento, tienes que 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 omites alguno de estos, tendrás errores sutiles.
Poca legibilidad: Mirando solo el HTML, no tienes idea de qué clases podrían aplicarse dinámicamente. La conexión entre tus datos y tu estilo es invisible.

La solución declarativa de Svelte

Ahora veamos cómo Svelte maneja exactamente el mismo requisito. En lugar de indicarle imperativamente al DOM qué hacer, describes declarativamente qué debe 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 estilo es completamente clara, justo en la plantilla donde puedes verla. Cuando isLoading es true, el botón obtiene la clase loading. Cuando tanto isLoading como isDisabled son false, obtiene 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 enfocarte 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 a usar este poder de manera efectiva.

El atributo `class`: tu fundamento

El atributo class en Svelte funciona exactamente como esperarías de 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 el HTML normal. 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, por supuesto, esa no es la razón por la 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". Sin intervención manual requerida.

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

<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 según lo que sean:

<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, usar la sintaxis de objeto/array que aprenderemos a continuación, que maneja los valores falsy con elegancia.

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 preciso de clases

A partir de Svelte 5.16, el atributo class obtuvo la capacidad de aceptar objetos. Esto es un cambio de juego 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 librería 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 e isHighlighted = false, Svelte actualiza automáticamente el DOM a <div class="active disabled">.

Este patrón es increíblemente poderoso porque cada clase se controla independientemente por su propia condición. No tienes que pensar en eliminar clases antiguas ni en gestionar transiciones de estado — simplemente describes lo que debe 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 sintaxis estándar de objetos en JavaScript — { active } es exactamente lo mismo que { active: active }. Es algo pequeño, pero hace tu código 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 clase dinámicos con claves calculadas

A veces necesitas que el propio nombre de la clase sea dinámico, no solo si se aplica o no. Puedes usar la sintaxis de propiedad calculada de JavaScript (corchetes) para crear nombres de clase 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 interior y use el resultado como clave de 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 utiliza 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 clase 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 método anterior, necesitarías lógica separada para cada clase. Con la sintaxis de objeto, las clases relacionadas se agrupan por su condición, haciendo que tu intención sea completamente clara.

Sintaxis de Array: Combinando Múltiples Fuentes de Clases

Si bien la sintaxis de objeto es excelente 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 un string (que siempre se incluye) o una expresión que evalúa a un string (incluido) 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>

Veamos cada elemento:

'btn' — Un string plano, siempre incluido
'rounded' — Otro string plano, siempre incluido
isPrimary && 'primary' — isPrimary es true, por lo que evalúa a 'primary' (incluido)
isLarge && 'large' — isLarge es false, por lo que evalúa a false (excluido)
isDisabled && 'disabled' — isDisabled es false, por lo que evalúa a false (excluido)

La magia está en cómo funciona el operador && de JavaScript: si el lado izquierdo es falsy, devuelve el lado izquierdo (que se filtra). 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, podrías preferir 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 se 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 un único string de clases. Esta composabilidad es increíblemente poderosa para construir sistemas de diseño donde quieres compartir estilos base mientras permites personalización.

Composición de Clases en Componentes

Al construir componentes reutilizables, frecuentemente 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>

Nota algunas cosas importantes:

Renombramos el prop: Usamos class: className porque class es una palabra reservada en JavaScript. Esto desestructura el 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 del 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 strings, 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>

Dado 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 strings, objetos, arrays y cualquier combinación anidada de estos — 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 para objetos y arrays en el 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 codebases más 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 nota 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 nombramiento 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 según 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 que saturan 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 el template limpio
El atributo aria-current="page" se aplica condicionalmente para mayor accesibilidad
Los elementos activos obtienen un borde inferior visible, texto de color y un fondo sutil
Los elementos inactivos tienen estados hover que anticipan 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 de manera clara. Aquí hay un componente de input 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 neutral (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 correcta accesibilidad con 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 "Selected" 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 única 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 topan 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 intentan 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 doble espacio. 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: usar 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 forma elegante: simplemente se omiten de la cadena de clases final.

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

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

<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 ve .highlight usado como clase estática en ningún lugar, podría no incluir la versión con scope de ese estilo. Este es un caso límite, pero puede ser confuso cuando ocurre.

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

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

Solución 2: Siempre incluir una referencia estática

Dado que la clase se usa en una expresión de objeto/array, el 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 por la Prop `class`

A TypeScript no le agrada usar 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: Usar 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: strings, objetos, arrays y combinaciones anidadas.

4. Problemas de Reactividad con Objetos de Clases

Si almacenas las condiciones de tus clases en una variable de tipo objeto (en lugar de 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: Usar $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, comprender las implicaciones de rendimiento te ayuda a escribir mejor código.

Extraer Condiciones Complejas a $derived

Cuando tienes lógica compleja para determinar clases, extráela a $derived en lugar de calcularla 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 de $derived se cachea y solo se recalcula cuando cambian sus dependencias. Las expresiones inline en el atributo class se recalculan en cada render, incluso si las entradas no han cambiado.

Definir Mapeos de Clases Estáticas Fuera del Template

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 de manejo de clases son completamente insignificantes. El compilador de Svelte es notablemente eficiente, y clsx (que impulsa el procesamiento de objetos/arrays) está altamente 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 el rendimiento si has medido un problema. La optimización prematura del manejo de clases casi nunca vale el sacrificio en claridad del código.

Resumen de Buenas Prácticas

Después de cubrir todos los detalles, aquí están las prácticas clave a recordar:

Usa la sintaxis de objeto/array para código nuevo. La directiva class: es legado—no hay razón para usarla en nuevos proyectos de Svelte 5.
Elige la sintaxis correcta para la situación. Los objetos son excelentes para alternar booleanos (class={{ active: isActive }}). Los arrays son excelentes 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.
Coloca las clases del consumidor al final en los arrays del componente. Esto permite a los usuarios agregar estilos adicionales: class={['base-styles', className]}.
Tipifica tus props de clase en TypeScript. Importa ClassValue desde svelte/elements para una tipificación adecuada.
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 ligadas al 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 la temática. Al construir alternadores de temas, las variables CSS pueden simplificar significativamente la 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 útil 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é debería ser verdadero en lugar de manipular imperativamente el DOM—conduce a código más limpio y fácil de mantener. Con la sintaxis de objetos y arrays, tienes las herramientas para manejar todo, desde simples alternadores 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 vanilla, en expresiones reactivas y elegantes que se actualizan automáticamente cuando cambia el estado.

La evolución desde la sintaxis de la directiva class: hacia las nuevas formas de literales de array y 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 cuanto a tipos.

Ya sea que estés implementando alternadores 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.

Puntos 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 array admite clases estáticas y condicionales combinadas mediante class={['base-class', condition && 'conditional-class']} con filtrado automático de valores falsy
Los arrays aplanan automáticamente estructuras anidadas - class={[baseClasses, [variantClasses, conditionalClasses]]} se convierte en una única cadena de clases separadas por espacios
La evaluación de cortocircuito proporciona condicionales en línea usando && para "aplicar si es verdadero" y operadores ternarios para la selección de clases "uno u otro"
Las props de clase del componente usan el tipo ClassValue - let { class: className }: { class?: ClassValue } = $props() acepta cadenas, arrays, 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 calculadas complejas para lógica de múltiples condiciones: let classes = $derived({ active, disabled, [variantClass]: true })
Sintaxis de template literal 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 - Entender cómo se resuelven los estilos de clases en conflicto
$derived - Valores computados reactivos para lógica de clases compleja
$props() - Sistema de props del componente 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 como enfoque de estilizado alternativo
Tailwind CSS con Svelte - Integración del framework CSS de utilidades primero

Estilos dinámicos con el atributo class