Para de Usar CSS Container Queries Como Media Queries — A Diferença Real Que Ninguém Te Conta

94% de Suporte, 41% de Adoção — O Que Está Acontecendo?

Olha só isso: CSS Container Queries já tem cerca de 94% de suporte nos navegadores. Mas segundo a pesquisa State of CSS, só 41,4% dos devs realmente usam. Sendo que 86% sabem que existe. Esse gap não é problema de ferramenta — é problema de modelo mental.

O motivo é simples: à primeira vista, @container parece idêntico ao @media. Mesma sintaxe, mesmo padrão (min-width: ...). Aí o dev assume que funciona do mesmo jeito, copia os hábitos de media query e acaba com componentes que quebram em sidebars, células de grid e qualquer contexto onde o viewport é um proxy inútil.

Este artigo é sobre consertar esse modelo mental — não adicionando container queries em tudo, mas entendendo qual pergunta cada tipo de query faz ao navegador. Se quiser ver o argumento original, dá uma olhada no material original do Smashing Magazine.

Media Queries Olham Pra Fora. Container Queries Olham Pra Dentro.

Quando você escreve @media (min-width: 1024px), está perguntando uma coisa só pro navegador: qual a largura da tela agora? É isso. O viewport é um proxy, e funciona lindamente — até parar de funcionar.

/* Media query: dependente do viewport */
@media (min-width: 1024px) {
  .card {
    display: flex;
  }
}

Coloca esse .card numa célula de grid de 300px num desktop de 1920px e a media query dispara do mesmo jeito. O card vira display: flex com 300px de espaço e deforma tudo.

Container queries fazem uma pergunta diferente: quanto espaço inline eu tenho aqui, nesse slot específico?

/* Container query: dependente do componente */
.card-wrapper {
  container-name: card;
  container-type: inline-size;
}

@container card (min-width: 450px) {
  .card {
    display: flex;
    flex-direction: row;
  }
}

Agora o card responde ao wrapper, não ao viewport. Move ele pra uma sidebar, um modal ou um hero de largura total — ele se adapta corretamente em qualquer contexto. Vamos lá, testa isso no seu projeto! 🚀

Macro Layout vs. Micro Layout: O Modelo Mental Que Resolve Tudo

Para de pensar em container queries como "media queries 2.0". Pensa nelas como uma camada diferente de design responsivo.

Um elemento não deveria virar "tamanho tablet" só porque o viewport passou de 768px. Ele deveria trocar de layout quando ele tiver espaço suficiente — seja no mobile ou dentro de uma sidebar no desktop. Existem mais de 2.300 tamanhos de viewport únicos na web moderna. Não dá pra enumerar todos. Mas dá pra definir o que é "espaço suficiente" pra um componente.

Tipografia Fluida, Do Jeito Certo

Unidades de viewport (vw) amarram o texto à tela. Unidades de container (cqi, cqw, cqb) amarram o texto ao componente.

/* Errado: escala com o viewport, quebra em sidebars */
.card-title {
  font-size: clamp(100%, 1rem + 2vw, 24px);
}

/* Certo: escala com o container do componente */
.card-title {
  font-size: clamp(1rem, .5rem + 3cqi, 2rem);
}

O Truque do Flexbox Wrap

CSS não tem pseudo-classe :wrapped. Mas você pode detectar o wrap do flex com container queries, deixando os flex items expandirem quando quebram:

.flex-layout {
  display: flex;
  flex-wrap: wrap;
}

.flex-item {
  container-type: inline-size;
  flex: 1 1 390px; /* Cresce pra preencher, quebra em 390px */
}

.card {
  display: flex;
  flex-direction: column;
  background: #f4f4f4;
}

/* Dispara quando um item quebrado estica pra preencher a linha */
@container (min-width: 600px) {
  .card {
    flex-direction: row;
    align-items: center;
    background: #e2f0d9;
  }
}

Quando os itens quebram, o flex-grow estica eles, a container query detecta a mudança de tamanho e aplica os estilos — sem ResizeObserver. Olha só que elegante! 🔥

Três Armadilhas Que Quebram Implementações Reais

1. Um Container Não Pode Se Consultar

Esse é o erro #1. Você precisa de um wrapper.

/* NÃO FUNCIONA — loop infinito */
.card {
  container-name: card;
  container-type: inline-size;
}
@container card (min-width: 400px) {
  .card { display: flex; }
}

/* FUNCIONA — o wrapper é o container */
.cards {
  container-name: cards;
  container-type: inline-size;
}
@container cards (min-width: 400px) {
  .card { display: flex; }
}

Media queries não ligam pra isso — o viewport está sempre disponível. Container queries exigem uma relação pai-filho explícita.

2. container-type: size Pode Colapsar Seu Layout

/* Colapsa pra 0px de altura se não tiver altura explícita */
.hero-banner {
  container-type: size;
}

O navegador calcula as dimensões do container sem olhar pros filhos. Sem height, min-height ou aspect-ratio explícitos, vira 0px. Usa inline-size por padrão, a menos que você realmente precise de queries de block-size.

3. Custom Properties Não São Consultáveis

:root { --breakpoint-lg: 1600px; }

/* NÃO FUNCIONA */
@container (min-width: var(--breakpoint-lg)) { /* ... */ }

Custom properties cascateiam, e uma container query que lê uma poderia, em teoria, mutá-la — criando dependência circular. Usa valores literais em container queries.

Quando Usar Cada Uma

• Container queries: componente aparece em múltiplos contextos de layout (grid + sidebar + modal).
• Media queries: componente é nível de página (nav principal, footer, shell da página).

Se você está construindo um sistema maior de UI resiliente e ciente de contexto, vale combinar isso com pensamento arquitetural na camada de infraestrutura — por exemplo, os princípios de design por trás da resiliência do Azure IaaS aplicam a mesma lógica de "adaptar ao contexto" no nível de plataforma.

A Conclusão

Container queries não substituem media queries — são um segundo eixo de responsividade. Media queries cuidam do macro; container queries cuidam do micro. Confundir as duas é o motivo pelo qual tantas implementações parecem frágeis.

A mudança mental é pequena mas consequente: para de perguntar "qual o tamanho da tela?" e começa a perguntar "quanto espaço esse componente realmente tem?". Quando isso clicar, o código sai sozinho.

Limitações Que Vale Reconhecer

• Container queries ainda exigem um wrapper extra na maioria dos casos, o que pode complicar markup simples.
• Style queries (@container style(...)) continuam experimentais e não devem ser usadas em produção ainda.
• O debug de container queries no DevTools está melhorando, mas ainda é menos maduro que o de media queries.

Próximos Passos

1. Audita sua biblioteca de componentes procurando qualquer componente que renderiza em mais de um contexto de layout. Esses são seus candidatos a container query.
2. Substitui tipografia fluida baseada em vw por cqi dentro desses componentes.
3. Mantém @media para preocupações de nível de página — não exagera na rotação.

Se você curte como princípios de "adaptação ao contexto" aparecem em sistemas de experimentação e medição, o framework de surrogate outcomes para A/B testing com LLMs é uma leitura paralela que vale a pena.

Fonte: Stop Treating CSS Container Queries Like Traditional Media Queries