Valores arbitrarios y propiedades custom

Sintaxis de valores arbitrarios

La sintaxis de valores arbitrarios en Tailwind CSS permite utilizar cualquier valor CSS directamente en las clases de utilidad mediante la notación de corchetes [valor]. Esta funcionalidad resulta esencial cuando los valores predefinidos del tema no cubren una necesidad concreta del diseño.

Dimensiones y espaciado

Las utilidades de dimensionamiento aceptan valores arbitrarios para definir anchos, altos y margenes con total precisión:

<div class="w-[350px] h-[calc(100vh-80px)] bg-gray-100 p-4">
  <p class="mt-[clamp(1rem,5vw,3rem)] p-[var(--custom-padding)]">
    Contenido con dimensiones exactas
  </p>
</div>

La clase w-[350px] genera un ancho fijo de 350 pixeles, mientras que h-[calc(100vh-80px)] establece una altura que descuenta 80 pixeles de la altura total del viewport. Esta combinación es habitual en layouts donde una cabecera fija ocupa parte de la pantalla.

Las funciones CSS calc(), clamp(), min() y max() funcionan dentro de los corchetes, lo que abre posibilidades de cálculo dinámico:

<div class="w-[min(100%,600px)] mx-auto">
  <div class="p-[clamp(0.5rem,2vw,1.5rem)]">
    Contenedor con ancho máximo adaptativo
  </div>
</div>

Los espacios dentro de los corchetes no están permitidos. Para funciones CSS que requieren separación entre argumentos, se debe sustituir cada espacio por un guion bajo: bg-[linear-gradient(to_right,_#3b82f6,_#8b5cf6)].

Colores arbitrarios

Cualquier formato de color CSS es válido dentro de los corchetes. Esto incluye códigos hexadecimales, funciones de color modernas y variables CSS:

<div class="bg-[#1a2b3c] text-[oklch(0.9_0.05_200)] p-6 rounded-lg">
  <h2 class="text-[hsl(210,80%,90%)]">Titulo con color OKLCH</h2>
  <p class="text-[var(--text-secondary)]">
    Párrafo que usa una variable CSS como color
  </p>
</div>

Las variables CSS se integran mediante la función var(), permitiendo conectar los tokens del sistema de diseño con las utilidades de Tailwind CSS:

<button class="bg-[var(--brand-color)] hover:bg-[var(--brand-color-hover)] text-white px-6 py-3 rounded-lg">
  Botón con color de marca
</button>

Indicadores de tipo

Cuando un valor arbitrario puede ser ambiguo, Tailwind CSS permite especificar el tipo de valor mediante un indicador de tipo (type hint) con la sintaxis tipo:valor. Esto es necesario especialmente con la utilidad text-, que puede referirse tanto a tamaño de fuente como a color:

<!-- Sin indicador: Tailwind interpreta el valor segun el contexto -->
<p class="text-[16px]">Tailwind lo interpreta como font-size</p>
<p class="text-[#ff0000]">Tailwind lo interpreta como color</p>

<!-- Con indicador explicito para resolver ambiguedad -->
<p class="text-[length:16px]">Explicitamente font-size</p>
<p class="text-[color:red]">Explicitamente color de texto</p>

Los indicadores de tipo disponibles incluyen length, color, angle, list, percentage, number, url y image. Estos resultan imprescindibles cuando el valor puede pertenecer a más de una categoría CSS:

<div class="grid grid-cols-[repeat(auto-fill,minmax(250px,1fr))] gap-4">
  <div class="bg-white shadow rounded-lg p-4">Tarjeta 1</div>
  <div class="bg-white shadow rounded-lg p-4">Tarjeta 2</div>
  <div class="bg-white shadow rounded-lg p-4">Tarjeta 3</div>
</div>

El indicador de tipo se coloca antes del valor, separado por dos puntos. Solo es necesario cuando Tailwind CSS no puede inferir automáticamente el tipo correcto del valor proporcionado.

Uso con funciones CSS avanzadas

Los valores arbitrarios admiten cualquier expresión CSS válida, incluyendo funciones de cálculo y comparación:

<section class="min-h-[max(400px,50vh)] flex items-center justify-center">
  <div class="w-[clamp(280px,60vw,800px)] p-[min(3rem,5vw)]">
    <h1 class="text-[clamp(1.5rem,4vw,3rem)] font-bold leading-[1.2]">
      Tipografía fluida con clamp
    </h1>
    <p class="mt-4 leading-[1.7] text-gray-600">
      Este párrafo mantiene un interlineado personalizado
      independientemente del tamaño de fuente.
    </p>
  </div>
</section>

Propiedades CSS arbitrarias

La sintaxis de propiedades arbitrarias permite aplicar cualquier declaración CSS que no tenga una utilidad equivalente en Tailwind CSS. La notación [propiedad:valor] genera una clase que aplica directamente esa propiedad CSS al elemento.

Sintaxis básica

El formato consiste en encerrar entre corchetes la propiedad CSS seguida de dos puntos y su valor:

<p class="[text-wrap:balance] max-w-prose mx-auto text-lg text-gray-700">
  Este párrafo largo se distribuye de forma equilibrada entre las lineas
  gracias a la propiedad text-wrap con valor balance, que evita lineas
  huérfanas y mejora la legibilidad del bloque de texto.
</p>

La propiedad text-wrap: balance no tiene una clase de utilidad dedicada en Tailwind CSS, pero la notación de corchetes permite aplicarla sin necesidad de escribir CSS personalizado.

Propiedades de layout y tipografía

Algunas propiedades CSS avanzadas que resultan útiles a través de esta sintaxis:

<div class="[container-type:inline-size] border rounded-lg p-4">
  <div class="@sm:flex @sm:gap-4">
    <img src="avatar.jpg" class="w-16 h-16 rounded-full" alt="Avatar">
    <div>
      <h3 class="font-semibold">Nombre de usuario</h3>
      <p class="text-gray-600 text-sm">Descripción del perfil</p>
    </div>
  </div>
</div>

<article class="[columns:2] [column-gap:2rem] [column-rule:1px_solid_#e5e7eb] p-6">
  <p>Primer párrafo del artículo con contenido distribuido en dos columnas
  automaticamente por el navegador.</p>
  <p>Segundo párrafo que fluye hacia la siguiente columna cuando el espacio
  de la primera se agota.</p>
</article>

Las propiedades arbitrarias generan estilos directamente sobre el elemento, de forma similar a los estilos en linea, pero con la ventaja de poder combinarse con variantes como hover:, dark: o breakpoints responsivos.

Escritura vertical y máscaras

Las propiedades de escritura y mascara son otro caso frecuente donde las propiedades arbitrarias resuelven necesidades específicas:

<div class="flex gap-8 items-start p-8">
  <!-- Texto vertical -->
  <span class="[writing-mode:vertical-rl] text-sm text-gray-500 tracking-widest uppercase">
    Etiqueta lateral
  </span>

  <!-- Contenido principal -->
  <div class="flex-1">
    <h2 class="text-2xl font-bold">Contenido principal</h2>
    <p class="mt-2 text-gray-600">Descripción del contenido con texto horizontal.</p>
  </div>
</div>

<div class="[mask-type:luminance] [mask-image:url('/mask.svg')] bg-gradient-to-r from-blue-500 to-purple-600 h-64 rounded-lg">
  <!-- Elemento con máscara SVG aplicada -->
</div>

Combinación con variantes

Las propiedades arbitrarias se combinan con todas las variantes de Tailwind CSS, lo que permite aplicarlas de forma condicional:

<p class="[text-wrap:pretty] hover:[text-decoration-thickness:2px] dark:[color-scheme:dark]">
  Texto con propiedades arbitrarias condicionales
</p>

<div class="[scroll-snap-type:x_mandatory] md:[scroll-snap-type:y_mandatory] overflow-auto">
  <div class="[scroll-snap-align:start]">Sección 1</div>
  <div class="[scroll-snap-align:start]">Sección 2</div>
  <div class="[scroll-snap-align:start]">Sección 3</div>
</div>

Variantes y selectores arbitrarios

Las variantes arbitrarias permiten aplicar estilos basados en selectores CSS personalizados que no estan cubiertos por las variantes predefinidas de Tailwind CSS. La sintaxis utiliza corchetes con un selector CSS como prefijo de la utilidad.

Selectores de estado y clase

La notación [&.clase] permite condicionar estilos a la presencia de una clase CSS adicional en el mismo elemento:

<nav class="flex gap-2">
  <a href="#" class="px-4 py-2 rounded-lg text-gray-600 [&.is-active]:bg-blue-500 [&.is-active]:text-white is-active">
    Inicio
  </a>
  <a href="#" class="px-4 py-2 rounded-lg text-gray-600 [&.is-active]:bg-blue-500 [&.is-active]:text-white">
    Productos
  </a>
  <a href="#" class="px-4 py-2 rounded-lg text-gray-600 [&.is-active]:bg-blue-500 [&.is-active]:text-white">
    Contacto
  </a>
</nav>

El símbolo & representa al propio elemento, de modo que [&.is-active] se traduce en el selector .clase.is-active. Esta técnica resulta útil cuando el estado de un componente se gestiona mediante clases añadidas por JavaScript.

Selectores de hijos y hermanos

Las variantes arbitrarias cubren relaciones jerárquicas entre elementos mediante selectores de hijos directos, descendientes y hermanos:

<!-- Hijos directos -->
<ul class="[&>li]:pl-4 [&>li]:border-l-2 [&>li]:border-blue-300 [&>li]:mb-2">
  <li>Elemento de primer nivel</li>
  <li>Elemento de primer nivel</li>
  <li>Elemento de primer nivel</li>
</ul>

<!-- Hermano adyacente -->
<div>
  <h2 class="text-xl font-bold [&+p]:mt-2 [&+p]:text-gray-500">Título de sección</h2>
  <p>Este párrafo hereda el margen y color definidos por la variante del h2.</p>
</div>

<!-- Hermano general -->
<div>
  <input type="checkbox" id="toggle" class="peer hidden">
  <label for="toggle" class="cursor-pointer text-blue-600 underline">Mostrar contenido</label>
  <div class="hidden [.peer:checked~&]:block mt-4 p-4 bg-gray-50 rounded-lg">
    Contenido visible cuando el checkbox está marcado.
  </div>
</div>

El selector & siempre representa al elemento que lleva la clase. La posición de & dentro del selector determina la relación: [&>li] selecciona hijos directos del elemento, mientras que [.parent>&] selecciona al elemento cuando es hijo directo de .parent.

Selectores de atributo

Los atributos de datos y estados ARIA se manejan con selectores de atributo dentro de variantes arbitrarias:

<div class="space-y-2">
  <details class="group border rounded-lg">
    <summary class="flex items-center justify-between p-4 cursor-pointer font-medium">
      Pregunta frecuente
      <span class="transition-transform [details[open]>&]:rotate-180">+</span>
    </summary>
    <div class="px-4 pb-4 text-gray-600">
      Respuesta detallada a la pregunta frecuente.
    </div>
  </details>
</div>

<!-- Atributos data personalizados -->
<div data-state="open" class="[&[data-state=open]]:bg-green-50 [&[data-state=open]]:border-green-300 [&[data-state=closed]]:bg-gray-50 border rounded-lg p-4">
  Panel que cambia de estilo según su atributo data-state.
</div>

Variantes de media query y @supports

Tailwind CSS permite definir variantes basadas en media queries y feature queries personalizadas:

<!-- Media query arbitraria -->
<div class="grid grid-cols-1 [@media(min-width:900px)]:grid-cols-3 gap-6">
  <div class="bg-white shadow rounded-lg p-4">Columna 1</div>
  <div class="bg-white shadow rounded-lg p-4">Columna 2</div>
  <div class="bg-white shadow rounded-lg p-4">Columna 3</div>
</div>

<!-- Feature query con @supports -->
<div class="flex [@supports(display:grid)]:grid [@supports(display:grid)]:grid-cols-2 gap-4">
  <div class="bg-blue-50 p-4 rounded">Elemento 1</div>
  <div class="bg-blue-50 p-4 rounded">Elemento 2</div>
</div>

Las media queries arbitrarias complementan los breakpoints predefinidos de Tailwind CSS, permitiendo puntos de ruptura específicos para componentes individuales sin modificar el tema global.

Combinación con otras variantes

Las variantes arbitrarias se pueden encadenar con las variantes predefinidas de Tailwind CSS para crear condiciones compuestas:

<div class="space-y-4">
  <!-- Dark mode + selector arbitrario -->
  <div class="p-6 rounded-lg bg-white dark:[&_p]:text-gray-300 dark:bg-gray-800">
    <h3 class="font-semibold text-gray-900 dark:text-white">Tarjeta informativa</h3>
    <p class="mt-2 text-gray-600">Todos los parrafos dentro de este contenedor
    adoptan un color claro en modo oscuro.</p>
    <p class="mt-1 text-gray-600">Segundo parrafo con el mismo comportamiento.</p>
  </div>

  <!-- Hover + selector arbitrario -->
  <ul class="divide-y divide-gray-200">
    <li class="p-3 hover:[&_a]:text-blue-600 hover:[&_a]:underline">
      <a href="#">Enlace que cambia al pasar el ratón sobre la fila</a>
    </li>
    <li class="p-3 hover:[&_a]:text-blue-600 hover:[&_a]:underline">
      <a href="#">Segundo enlace con el mismo comportamiento</a>
    </li>
  </ul>

  <!-- Responsive + selector arbitrario -->
  <nav class="flex flex-col md:[&>a]:inline-flex md:flex-row gap-2">
    <a href="#" class="px-4 py-2 bg-gray-100 rounded">Inicio</a>
    <a href="#" class="px-4 py-2 bg-gray-100 rounded">Servicios</a>
    <a href="#" class="px-4 py-2 bg-gray-100 rounded">Contacto</a>
  </nav>
</div>

Ejemplo práctico: Componente acordeón

Este ejemplo combina variantes arbitrarias con selectores de atributo y transiciones para construir un componente acordeón funcional:

<div class="max-w-lg mx-auto space-y-2">
  <details class="group rounded-lg border border-gray-200 [&[open]]:border-blue-300 [&[open]]:shadow-md transition-all">
    <summary class="flex items-center justify-between p-4 cursor-pointer select-none font-medium text-gray-800 group-open:text-blue-700">
      Qué son los valores arbitrarios
      <svg class="w-5 h-5 transition-transform group-open:rotate-180" fill="none" stroke="currentColor" viewBox="0 0 24 24">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"/>
      </svg>
    </summary>
    <div class="px-4 pb-4 text-gray-600 [&>p]:mt-2">
      <p>Los valores arbitrarios permiten usar cualquier valor CSS
      directamente en las clases de utilidad de Tailwind CSS.</p>
      <p>Se escriben entre corchetes y admiten funciones como
      calc(), clamp() y var().</p>
    </div>
  </details>

  <details class="group rounded-lg border border-gray-200 [&[open]]:border-blue-300 [&[open]]:shadow-md transition-all">
    <summary class="flex items-center justify-between p-4 cursor-pointer select-none font-medium text-gray-800 group-open:text-blue-700">
      Cuándo usar propiedades arbitrarias
      <svg class="w-5 h-5 transition-transform group-open:rotate-180" fill="none" stroke="currentColor" viewBox="0 0 24 24">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"/>
      </svg>
    </summary>
    <div class="px-4 pb-4 text-gray-600 [&>p]:mt-2">
      <p>Las propiedades arbitrarias se utilizan cuando la propiedad CSS
      deseada no tiene una utilidad equivalente en Tailwind CSS.</p>
      <p>Permiten acceder a cualquier propiedad CSS moderna sin
      necesidad de crear clases personalizadas.</p>
    </div>
  </details>
</div>