Pare de Usar CSS Container Queries Como Media Queries Guia Prático com Código

Olha só isso: você provavelmente está usando container queries do jeito errado

As CSS container queries não são novidade. O suporte nos navegadores está em torno de 94%, mas a pesquisa State of CSS mostra que 86% dos devs conhecem o recurso e só 41,4% realmente usam. Essa diferença não é preguiça — é um problema de modelo mental.

À primeira vista, @container parece idêntico a @media. Mesma sintaxe, mesma condição min-width. Aí o dev assume que funciona igual, aplica nos mesmos problemas, e depois não entende por que o componente continua quebrando dentro de uma sidebar.

O motivo é simples: media queries olham para fora (viewport); container queries olham para dentro (o pai do componente).

Imagina um .card dentro de uma célula de grid de 300px numa tela desktop de 1920px. A regra @media (min-width: 1024px) dispara — o viewport tem 1920px — mas o card só tem 300px disponíveis. O layout deforma, transborda, espreme. A media query fez o trabalho dela. O ponto de referência é que estava errado.

Neste guia a gente vai ver o modelo mental correto, código funcional para três cenários reais e os efeitos colaterais que ninguém comenta. Se você quer entender para onde o CSS está indo em 2026, dá uma olhada no nosso resumo sobre a função CSS Alpha, Grid Lanes e os destaques do CSS Day.

O modelo mental: layout macro vs. micro

Regra de ouro: media query é para a página, container query é para o componente. Um elemento não deveria virar "tamanho tablet" só porque o viewport passou de 768px — ele deveria mudar de layout quando ele tiver espaço suficiente, seja no mobile ou dentro de uma sidebar no desktop.

Exemplo 1: Um card que responde ao próprio espaço

/* Registra o wrapper como container — o container NÃO pode se consultar */
.card-wrapper {
  container-name: card;
  container-type: inline-size;
}

/* Padrão: empilhado */
.card {
  display: flex;
  flex-direction: column;
  background: #f4f4f4;
}

/* Quando o wrapper tiver pelo menos 450px inline, vira horizontal */
@container card (min-width: 450px) {
  .card {
    flex-direction: row;
    align-items: center;
  }
}

Exemplo 2: Tipografia fluida que escala com o componente

Tipografia fluida com media query usa vw — relativo ao viewport. Move o componente pra uma sidebar e o tamanho fica errado.

/* ❌ Relativo ao viewport — quebra dentro de uma sidebar */
.card-title {
  font-size: clamp(100%, 1rem + 2vw, 24px);
}

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

cqi é a unidade de inline-size do container. Junta com clamp() e a tipografia fica totalmente autocontida.

Exemplo 3: Detectar wrap do Flexbox sem JavaScript

CSS não detecta quando itens flex quebram linha — não existe pseudo-classe :wrapped. Mas dá pra aninhar uma container query dentro de um flex item:

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

/* Cada item é seu próprio container */
.flex-item {
  container-type: inline-size;
  flex: 1 1 390px; /* cresce pra preencher, quebra abaixo de 390px */
}

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

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

Quando os itens quebram, flex-grow: 1 estica eles pela linha toda. Essa expansão de largura dispara a container query — sem ResizeObserver.

Três efeitos colaterais que vão te pegar

1. Um container não pode se consultar

Esse é o erro mais comum:

/* ❌ NÃO FUNCIONA — loop infinito */
.card {
  container-name: card;
  container-type: inline-size;
}

@container card (min-width: 400px) {
  .card { display: flex; } /* consultando o container pra reestilizar o próprio container */
}

Você precisa de um elemento wrapper pra que o elemento estilizado seja descendente do container. É o nó extra de DOM que ninguém menciona no post de anúncio.

2. Consultar o block size pode colapsar seu layout

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

O navegador calcula as dimensões do container sem olhar pros filhos. Sem height, min-height ou aspect-ratio, o container fica com 0px de altura. Prefira container-type: inline-size a menos que você realmente precise consultar o block size.

3. Custom properties não funcionam em condições de query

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

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

Custom properties cascateiam, e a query poderia teoricamente mudar o valor contra o qual ela mesma está consultando. A spec proíbe. Você vai ter que hardcodar breakpoints ou usar pré-processador.

Quando usar cada um

• Container queries: o componente é reutilizado em vários contextos de layout (grid full-width e sidebar).
• Media queries: o componente só existe no nível da página (nav do topo, footer) e o viewport é uma referência confiável.
• Os dois: uma media query de página define o grid macro, e container queries cuidam do interior de cada célula.

Se você tá construindo arquiteturas orientadas a componentes onde cada time é dono do seu pedaço de UI, container queries combinam naturalmente com microfrontends verticais no Cloudflare — o componente de cada time se adapta ao slot que o layout hospedeiro oferece.

Fechando a conta

Container queries parecem media queries por familiaridade, não por equivalência. A sintaxe é parecida; a semântica é invertida. Media query pergunta "qual o tamanho da tela?". Container query pergunta "quanto espaço eu tenho aqui, agora?".

Com mais de 2.300 tamanhos de viewport únicos na web moderna, responsividade baseada em viewport é um proxy que falha cada vez mais. Responsividade no nível do componente é a abstração correta — mas só se você parar de usar @container como substituto direto de @media.

Próximos passos pra evoluir:

1. Audita seus componentes — qualquer coisa reutilizada em dois ou mais contextos é candidata a container query.
2. Migra tipografia fluida de vw pra cqi onde os componentes são agnósticos de contexto.
3. Explora container style queries (ainda experimentais) pra reagir a estilos computados, não só a tamanho.
4. Estuda o padrão de detecção de flex-wrap — é uma forma sem JavaScript de lidar com mudanças de estado de layout que antes exigiam ResizeObserver.

Leitura recomendada: Stop treating CSS container queries like traditional media queries — a análise original que serviu de base pra este guia.