CSS Container queries

¿Qué son las Container Queries?

Las CSS Container Queries permiten aplicar estilos a un elemento en función del tamaño del contenedor en el que se encuentra, en lugar del tamaño del viewport. Esto resuelve una de las limitaciones más importantes de los media queries tradicionales: su dependencia del viewport global.

Esto significa que puedes crear componentes verdaderamente responsivos, que se adaptan a su espacio asignado sin depender del tamaño de la ventana del navegador.

¿Por qué usar Container Queries en lugar de Media Queries?

Los Media Queries funcionan muy bien para layouts generales porque toman decisiones en base al viewport, es decir, el ancho o alto de toda la ventana del navegador. Pero eso tiene una limitación importante: no saben en qué contexto específico se encuentra cada componente.

Problema de los Media Queries

Imagina que tienes una tarjeta de producto (.product-card) que funciona perfecto en la página principal de tu tienda, con este estilo:

@media (min-width: 768px) {
  .product-card {
    display: grid;
    grid-template-columns: 1fr 2fr;
  }
}

Pero ahora reutilizas esa tarjeta en otro lugar, como dentro de un slider estrecho o una columna lateral. Aunque el espacio real en ese nuevo contenedor sea pequeño, el navegador entero sigue midiendo más de 768px, así que la tarjeta aplica estilos pensados para mucho más espacio... y rompe el diseño.

Solución con Container Queries

Con @container, puedes hacer que el componente observe su propio contenedor y actúe según su tamaño real:

@container (max-width: 400px) {
  .product-card {
    grid-template-columns: 1fr;
  }
}

Esto significa que:

• Si la tarjeta está dentro de un contenedor estrecho, se adapta sola.
• Si se usa en un contenedor amplio, puede mostrar más información.
• Es independiente del DOM o del layout general.

Resultado

• Media Queries: basados en el viewport. Solo sirven para layouts generales.
• Container Queries: basados en el contenedor padre. Permiten componentes modulares, adaptables y reutilizables.
• Hacen que el diseño sea más escalable, mantenible y resiliente ante cambios de layout.

En resumen:

Container Queries no sustituyen a Media Queries. Pero para componentes frontend reutilizables y diseños modernos, son una herramienta más potente y precisa.

Activar un contenedor

Para que un elemento pueda ser objeto de una Container Query, debe estar dentro de un contenedor "observable". Esto se logra así:

.card {
  container-type: inline-size;
  container-name: card;
}

• container-type: indica qué dimensiones observar (inline-size, size o normal para style queries).
• container-name: da nombre al contenedor (opcional, pero útil si usas queries nombradas).

Sintaxis de una Container Query

Una vez definido un contenedor, puedes aplicar una container query de forma similar a un media query:

@container (width >= 400px) {
  .card {
    flex-direction: row;
  }
}

También puedes usar @container card (min-width: 400px) si nombraste el contenedor como card.

Container Length Units

Estas son nuevas unidades que permiten usar medidas relativas al tamaño del contenedor en lugar del viewport:

• cqw = 1% del ancho del contenedor
• cqh = 1% del alto del contenedor
• cqi, cqb = inline/block (escritura dependiente)
• cqmin, cqmax = valor menor/mayor entre cqw y cqh

Ejemplo:

.card {
  padding: 2cqi;
  font-size: 1cqmin;
}

Esto escala el diseño de forma fluida, dentro del componente.

Relación entre unidades y writing-mode

Aunque cqw y cqi pueden parecer intercambiables, no siempre representan lo mismo. Su equivalencia depende del valor de writing-mode, es decir, de la dirección de escritura del contenedor.

Resumen:

• cqw y cqh son unidades explícitas (ancho y alto).
• cqi y cqb son semánticas (inline y block, dependen de writing-mode).

Recomendación:

• Usa cqw y cqh si quieres control absoluto sobre dimensiones físicas.
• Usa cqi y cqb si estás creando componentes más adaptables, por ejemplo para interfaces internacionales donde la escritura cambia de dirección.

Style Queries

Las style queries permiten aplicar estilos condicionales basados en propiedades CSS del contenedor, como --theme, display, aspect-ratio, etc.

@container style(--theme: dark) {
  .component {
    background: black;
  }
}

Ejemplo práctico

<div class="card">
  <h2>Product Name</h2>
  <p>Description here</p>
</div>

.card {
  container-type: inline-size;
  border: 1px solid;
  padding: 1rem;
}

@container (min-width: 500px) {
  .card {
    display: flex;
    flex-direction: row;
    gap: 1rem;
  }
}

Esto hace que .card se reorganice automáticamente según su contenedor, no el viewport.

Soporte y uso actual

• Soporte completo en navegadores modernos (Chrome, Edge, Firefox, Safari)
• Style queries aún experimentales (requieren flags)
• No necesitas ninguna herramienta extra si trabajas con CSS moderno

Recursos útiles

• MDN Web Docs: CSS Container Queries
• CSS Tricks: Container Queries