Container queries no CSS não são media query por componente

Container queries não são um feature novo. O suporte nos navegadores já bate 94%, e ainda assim, segundo o State of CSS↳CSS31 conteúdosArquitetura CSS: CSS FuncionalDev (Back & Front) · set 2019Entendendo posicionamento com CSS de uma vez por todasDev (Back & Front) · jul 2025Sites que combinam estética e usabilidade: reflexos da evolução do CSSDev (Back & Front) · fev 2025Ver tudo em Dev (Back & Front) → citado por Victor Ayomipo no Smashing Magazine, 86% dos devs sabem que elas existem mas apenas 41,4% as usam de fato. Kevin Powell, no SmashingConf Amsterdam 2026, foi direto: a adoção tem sido péssima. O problema, argumenta o artigo, não é só adoção, é uso incorreto, e ele nasce de um mal-entendido: tratar @container como se fosse @media aplicada a um componente.

Elas se parecem à primeira vista, e é justamente por isso que a confusão persiste. Mas respondem a perguntas diferentes, e essa diferença muda o modo como se pensa layout.

A viewport é um proxy, e nem sempre confiável

Quando você escreve @media (min-width: 1024px), a única coisa que o navegador responde é: qual a largura da tela agora? Nada além disso. O exemplo do artigo é o clássico caso que quebra na produção: um componente .card com display: flex a partir de 1024px de viewport. Coloque esse card numa célula de grid de 300px dentro de um monitor de 1920px, e a media query dispara mesmo assim, porque a viewport continua com 1920px. O card entra em modo horizontal com 300px de espaço real. Resultado: conteúdo deformado, overflow, texto espremido.

A media query não erra, ela só é, nas palavras de Powell citadas na fonte, "burra": não em conceito, mas no sentido de que sabe muito pouco, e a maioria das pessoas assume que ela sabe mais do que sabe. Ela olha para fora, para o contexto macro da página.

A container query olha para dentro. A pergunta muda para: quanto espaço eu tenho neste ponto específico, agora? O mesmo card reescrito:

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

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

Agora a viewport é irrelevante. O card só vira horizontal se o wrapper pai tiver ao menos 450px de espaço inline (horizontal, em escrita da esquerda para a direita). Se não tiver, ele fica no display de bloco padrão. O componente decide pelo espaço que recebeu, não por um número abstrato da tela.

Macro versus micro: a distinção que organiza a decisão

A forma mais útil de separar as duas, proposta no artigo, é por tipo de layout. Media queries servem ao layout macro: estrutura da página, header que cobre a janela, footer, grid principal, preferências do sistema (prefers-color-scheme), capacidade do dispositivo (touch). Tudo que é verdade para a página inteira.

Container queries servem ao layout micro: cards, widgets, formulários, navegação interna, qualquer coisa que vive dentro do macro e precisa se ajustar ao espaço alocado. "Page layout" versus "component layout", resume o texto.

O argumento por trás é sólido, e é onde acessibilidade↳Acessibilidade11 conteúdosO que é Acessibilidade Web e como tornar seu site mais acessívelDev (Back & Front) · mar 2019Design para veteranos digitais: acessibilidade para nós mesmosProduto & UX · jan 2020Dicas de Front-End para usabilidade, acessibilidade, performance e responsividadeProduto & UX · fev 2025Ver tudo em Produto & UX → e robustez entram: um elemento não deveria virar "tamanho tablet" só porque a largura passou de 768px. Ele deveria mudar quando tem espaço para mudar, seja num celular ou dentro de uma sidebar de desktop. O dado que fecha o raciocínio: existem mais de 2.300 tamanhos únicos de viewport na web moderna. Tentar prever todos com breakpoints fixos é uma batalha perdida. Amarrar a lógica ao conteúdo e ao container disponível resolve a raiz do problema, não os sintomas.

Unidades próprias: tipografia que escala com o componente

Tipografia fluida é o caso onde muita gente ainda usa vw por hábito. O problema:

.card-title {
  font-size: clamp(100%, 1rem + 2vw, 24px);
}

Isso funciona até o componente ir parar numa sidebar, onde a viewport não tem nada a ver com o espaço real. A fonte escala pelo referencial errado e fica grande ou pequena demais. Container queries trazem unidades próprias, cqi, cqw, cqb entre outras, relativas ao container e não à tela:

.card-title {
  font-size: clamp(1rem, .5rem + 3cqi, 2rem);
}

Agora a responsividade do texto é autocontida no container do elemento. Move o componente para onde quiser: a tipografia acompanha o espaço que ele de fato ocupa.

O truque que media query nunca fez: detectar wrap de flexbox

Este é o ponto mais interessante da fonte, e vale para quem constrói menus e barras de ação. Flexbox faz wrap automático com flex-wrap: wrap, mas o CSS puro não tem como saber quando o wrap aconteceu. Não existe :wrapped nem @media (flex-wrapped: true). Media queries só enxergam a janela do navegador, são estruturalmente cegas para eventos internos de layout. Para detectar wrap, o caminho tradicional é JavaScript com ResizeObserver.

O artigo mostra uma técnica, atribuída a Kevin Powell, que resolve isso só com CSS. A ideia: registrar cada flex item como container e deixá-lo crescer com flex-grow quando quebra de linha.

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

.flex-item {
  container-type: inline-size;
  flex: 1 1 390px;
}

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

@container (min-width: 600px) {
  .card {
    flex-direction: row;
    align-items: center;
    background: #e2f0d9;
  }
}

A lógica: com espaço, os dois itens ficam lado a lado, cada um com metade da largura do pai. Quando o espaço aperta, o segundo item quebra para a linha de baixo, e como flex-grow está ativo, ele se estica para preencher quase toda a largura do pai. Essa expansão súbita de largura é justamente o que a container query detecta, disparando os novos estilos. Não é à prova de balas, o próprio autor avisa, mas elimina o JavaScript de um caso comum.

Três efeitos colaterais antes de sair migrando

Container queries têm caveats concretos que quebram código, e o artigo lista os principais.

1. Um container exige wrapper extra. Um container não pode consultar a si mesmo, seria loop infinito. Este código não funciona:

.card {
  container-name: card;
  container-type: inline-size;
}
@container card (min-width: 400px) {
  .card { display: flex; }
}

É preciso um elemento pai (.cards) como container e aplicar o estilo no descendente (.card). Com media query isso não importa, porque a viewport está sempre disponível como referência.

2. Consultar size pode colapsar o layout. Ao usar container-type: size (que inclui o eixo de bloco, vertical), o navegador calcula as dimensões sem olhar os filhos. Sem height, min-height ou aspect-ratio explícitos, ele define altura como 0px, mesmo com conteúdo dentro. Por isso a recomendação é preferir inline-size, a menos que você realmente precise consultar o tamanho de bloco.

3. Não aceitam custom properties. Não dá para consultar contra uma variável CSS:

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

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

O motivo é a cascata: uma container query que depende de custom property poderia alterar essa mesma property, criando dependência circular. A limitação é intencional.

Quando cada uma faz sentido

A conclusão do artigo é equilibrada, e é a régua que faz sentido adotar: nenhum projeto deveria trocar @media por @container no atacado. A pergunta prática é sobre separação de responsabilidades. Container query quando o componente vive em mais de um contexto de layout, o mesmo card num grid full-width e numa sidebar estreita. Media query quando o componente existe só no nível da página, como a navegação principal que sempre fica no topo e é diretamente influenciada pela viewport.

O que container queries entregam é a capacidade de detectar quando o contexto de um componente específico muda, e ajustar o estilo com base no espaço real disponível. Para quem constrói design systems e componentes reutilizáveis, é a peça que faltava para que "reutilizável" signifique de verdade que o componente se comporta bem em qualquer lugar, sem depender de breakpoints globais que não sabem onde ele foi parar.

Fonte: Smashing Magazine