Diseño Moderno con CSS Container Queries

Las CSS container queries representan una de las capacidades de layout más significativas añadidas a la plataforma web en años recientes. A diferencia de las media queries, que responden a dimensiones del viewport, las container queries permiten que los componentes se adapten según el tamaño de su contenedor padre. Este cambio del nivel de página al nivel de componente resuelve un problema de larga data en design systems: construir componentes verdaderamente reutilizables que se vean correctos en cualquier contexto sin overrides globales de breakpoints.

Container queries vs media queries

Las media queries revolucionaron el diseño responsivo permitiendo que los estilos cambien según el ancho del viewport. Pero el ancho del viewport es un proxy pobre del espacio disponible para un componente individual. Un widget de sidebar, una tarjeta de dashboard y una sección hero a ancho completo existen a anchos diferentes incluso cuando el viewport es idéntico.

Este desajuste obliga a los desarrolladores a workarounds incómodos:

• Pasar props de breakpoint desde componentes padre para sobrescribir estilos hijo.
• Usar JavaScript resize observers para alternar clases según el ancho del elemento.
• Crear variantes duplicadas de componentes para diferentes contextos de layout.
• Depender de trucos CSS grid y flexbox que se rompen cuando cambia el layout.

Las container queries eliminan estos workarounds. Un componente envuelto en un contexto de contenedor ajusta automáticamente su layout interno cuando su espacio asignado cambia — ya sea por resize del viewport, toggle de sidebar o reflujo de columnas grid.

La regla @container

Las container queries usan dos construcciones CSS: la propiedad container-type en un elemento padre y la at-rule @container en estilos descendientes. El padre se declara como query container, y los hijos escriben estilos condicionales según las dimensiones del contenedor.

/* Parent establishes a query container */
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
  gap: 1rem;
}

/* Each card container enables size queries for its children */
.product-card {
  container-type: inline-size;
  container-name: card;
  border: 1px solid var(--color-border);
  border-radius: var(--radius-md);
  overflow: hidden;
}

/* Child styles respond to container width, not viewport */
@container card (min-width: 400px) {
  .product-card .card-body {
    display: flex;
    gap: 1rem;
  }

  .product-card .card-image {
    width: 40%;
    flex-shrink: 0;
  }

  .product-card .card-details {
    flex: 1;
  }
}

@container card (max-width: 399px) {
  .product-card .card-image {
    width: 100%;
    aspect-ratio: 16 / 9;
  }
}

La propiedad container-type acepta inline-size (ancho en modos de escritura horizontal), size (ancho y alto), o normal (sin contenedor). La mayoría de casos de uso de layout requieren solo inline-size, que también es la opción más performante porque el navegador solo rastrea una dimensión.

Unidades de container query

Las container queries introdujeron nuevas unidades de longitud CSS que referencian las dimensiones del query container en lugar del viewport. Estas unidades habilitan tipografía y espaciado fluidos que escalan con el tamaño del componente.

• cqw — 1% del ancho del query container.
• cqh — 1% del alto del query container.
• cqi — 1% del inline size del query container.
• cqb — 1% del block size del query container.
• cqmin — El menor de cqi y cqb.
• cqmax — El mayor de cqi y cqb.

.stat-widget {
  container-type: inline-size;
}

.stat-widget .value {
  /* Font size scales with container width */
  font-size: clamp(1.5rem, 5cqi, 3rem);
}

.stat-widget .label {
  font-size: clamp(0.75rem, 2.5cqi, 1rem);
}

Combina unidades de container query con clamp() para crear tipografía que escala suavemente dentro de un componente sin saltos duros de breakpoint. Un widget de estadísticas en una columna estrecha de sidebar renderiza texto más pequeño, mientras el mismo componente en un panel amplio de dashboard renderiza texto más grande — automáticamente, sin props ni JavaScript.

Style queries y container query features

Más allá de size queries, la especificación CSS container queries incluye style queries que responden a valores de estilo computados del contenedor. Puedes consultar valores de custom properties, dando a los componentes conciencia del contexto de tema de su padre.

.theme-container {
  container-type: inline-size;
  --variant: default;
}

.theme-container[data-variant="compact"] {
  --variant: compact;
}

@container style(--variant: compact) {
  .nested-component {
    padding: 0.5rem;
    font-size: 0.875rem;
  }
}

Las style queries son particularmente potentes en design systems donde un contenedor establece tokens semánticos y los componentes hijo adaptan su densidad, espaciado y tipografía en consecuencia. Este patrón reemplaza prop-drilling de flags de variante a través de árboles de componentes.

Construir componentes responsivos sin media queries

El objetivo práctico de las container queries son componentes que funcionan correctamente dondequiera que se coloquen. Considera un componente de tabla de datos usado en una vista a página completa, un diálogo modal y un widget de dashboard. Con solo media queries, las tres instancias comparten la misma lógica de breakpoint atada al ancho del viewport, produciendo layouts rotos en al menos un contexto.

Con container queries, el componente de tabla define su propio comportamiento responsivo:

• Por encima de 600px de ancho de contenedor — Mostrar todas las columnas en layout de tabla estándar.
• 400px a 600px — Ocultar columnas de baja prioridad, reducir padding.
• Por debajo de 400px — Cambiar a layout de tarjetas apiladas con pares etiqueta-valor.

.data-table-wrapper {
  container-type: inline-size;
  container-name: table;
  overflow-x: auto;
}

@container table (max-width: 399px) {
  .data-table thead {
    display: none;
  }

  .data-table tr {
    display: block;
    margin-bottom: 1rem;
    border: 1px solid var(--color-border);
    border-radius: var(--radius-sm);
    padding: 0.75rem;
  }

  .data-table td {
    display: flex;
    justify-content: space-between;
    padding: 0.25rem 0;
  }

  .data-table td::before {
    content: attr(data-label);
    font-weight: 600;
  }
}

Este componente requiere cero conocimiento del layout de su padre. Suéltalo en cualquier contenedor y se adapta. Esa es la promesa de las container queries cumplida.

Integración con frameworks

Los frameworks CSS modernos adoptan container queries de forma nativa. Tailwind CSS v4 incluye variantes de container query — prefija utilities con @ seguido del breakpoint para aplicar estilos según el tamaño del contenedor. Styled-components y otras bibliotecas CSS-in-JS soportan la at-rule @container en template literals sin configuración adicional.

En bibliotecas de componentes React, establece contexto de contenedor en la raíz del componente y deja que los elementos internos usen container queries para decisiones de layout. Documenta qué componentes son container-aware para que los consumidores sepan evitar restringirlos por debajo de su ancho funcional mínimo.

Soporte de navegadores y progressive enhancement

Las container queries disfrutan amplio soporte de navegadores a partir de 2026, con cobertura en Chrome, Firefox, Safari y Edge. Para el pequeño porcentaje de navegadores legacy sin soporte, aplica progressive enhancement: diseña los estilos predeterminados para el tamaño de contenedor más común, luego agrega overrides de container query para navegadores compatibles.

Usa la regla @supports para detectar soporte de container queries y proporcionar fallbacks de media query donde sea necesario:

/* Fallback for browsers without container query support */
@media (max-width: 600px) {
  .product-card .card-body {
    flex-direction: column;
  }
}

/* Enhanced layout for supporting browsers */
@supports (container-type: inline-size) {
  @container card (max-width: 399px) {
    .product-card .card-body {
      flex-direction: column;
    }
  }
}

Las container queries marcan una maduración de CSS como lenguaje para diseño orientado a componentes. Al desplazar la lógica responsiva del nivel de página al nivel de componente, habilitan design systems donde cada componente es verdaderamente autocontenido, adaptativo y reutilizable. Abraza container queries en tu próximo proyecto y experimenta diseño responsivo como siempre debió funcionar.