CSS Container Query

Container Queries: responsividade por componente, não por página

Media queries comandam o design responsivo desde 1995, mas elas só reagem ao viewport. Isso significa que um card colocado em uma sidebar e o mesmo card colocado na área principal herdam breakpoints pensados para a janela inteira — ainda que a sidebar tenha 280px e a área principal 960px. As container queries corrigem esse descompasso: permitem que um componente reaja ao container pai em vez da tela. Um único .card pode trocar de layout empilhado para grade horizontal no instante em que o pai cruza 400px — independente de onde esse pai esteja na página.

O suporte nos navegadores chegou entre o fim de 2022 e o início de 2023: Chrome 105+, Safari 16+, Firefox 110+. Em 2026 isso cobre mais de 92% do tráfego global, então a maior parte das aplicações em produção já pode adotar sem polyfill. Para navegadores antigos existe o container-query-polyfill, mas ele é pesado; a estratégia recomendada é progressive enhancement.

Sintaxe em duas partes

Primeiro, declare o contexto de contenção no pai. Depois, escreva a query contra esse contexto:

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

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

container-type aceita três valores: inline-size (somente o eixo inline — em geral a largura — é consultável; é a escolha mais comum), size (os dois eixos — mais caro porque força contenção total de layout) e normal (padrão, sem contenção). O @container usa a mesma sintaxe de condição do @media, mas com escopo no container ancestral mais próximo que casar com o nome informado.

Unidades de container query

Junto da at-rule, o CSS ganhou unidades relativas ao container: cqw (1% da largura do container), cqh (altura), cqi (inline), cqb (block), cqmin e cqmax. Funcionam como vw/vh, mas com escopo no container e não na janela — ideais para tipografia fluida dentro de um card que não deveria depender do tamanho da tela.

Onde brilham

• Cards que alternam entre layout empilhado e lado a lado;
• Padrões de navegação que viram hambúrguer conforme a sidebar encolhe;
• Widgets de sidebar reusados em dashboards e modais;
• Cards de post em grades multi-coluna gerenciadas por CMS;
• Primitivas de design system entregues sem saber o layout do consumidor.

Perguntas frequentes

Container queries substituem media queries? Não — elas se complementam. Mantenha @media para layout de página (uma coluna vs duas, drawer vs barra de navegação) e use @container para variantes de componente que precisam se adaptar a qualquer slot.

Quando escolher @container em vez de @media? Uma regra prática: media = página, container = componente. Se a regra depende do dispositivo ou da janela toda, é media query. Se depende do espaço que o componente ocupa, é container query.

E quem usa Tailwind? Desde o Tailwind 3.2 existe o plugin @container, permitindo escrever @container <div class="@md:flex"> direto no HTML. Styled Components, Emotion e a maioria das libs CSS-in-JS já expõem helpers equivalentes.

Tem custo de performance? A contenção é otimizada: o navegador só re-avalia as regras quando a dimensão relevante do container muda. Evite container-type: size a não ser que precise dos dois eixos — ele força contenção total de layout, que é mais cara do que inline-size.