CSS Container Queries: estilizar componentes pelo seu contêiner, não pela viewport

As container queries permitem que um elemento responda ao tamanho do seu contêiner pai em vez do tamanho de toda a viewport. É a peça que faltava para finalmente tornar um componente reutilizável: o mesmo cartão pode se dispor de uma forma numa barra lateral estreita e de outra numa coluna principal larga — na mesma página, na mesma largura de tela.

Por que as media queries não bastavam

Uma media query faz apenas uma pergunta: qual é a largura da viewport? Mas um componente não sabe qual é a largura da viewport — ele sabe quanto espaço lhe foi dado. Um cartão colocado numa barra lateral de 300px e o mesmo cartão numa célula de grade de 900px precisam de layouts diferentes, mas a largura da viewport é idêntica. As container queries resolvem exatamente isso.

Passo 1: declarar um contexto de contenção

Você consulta um contêiner, então primeiro precisa marcar um elemento como contêiner com container-type:

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

inline-size significa "deixe-me consultar a dimensão inline (geralmente horizontal)" — a escolha mais comum. size consulta ambas as dimensões e normal desliga a contenção.

Passo 2: consultá-lo com @container

Agora qualquer descendente de .card-wrapper pode se adaptar com base na largura do wrapper:

.card {
  display: grid;
  gap: 1rem;
}

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

Quando o wrapper tem pelo menos 400px de largura, o cartão muda para um layout de duas colunas. Coloque essa mesma marcação em qualquer lugar da página e ela se adapta ao local onde cai — sem necessidade de media queries no nível da página.

Nomear contêineres

Quando os contêineres estão aninhados, dê-lhes nomes com container-name para que uma query atinja o correto:

.layout { container: layout / inline-size; } /* name / type shorthand */

@container layout (min-width: 600px) {
  .card { /* responds to .layout, not a closer container */ }
}

Unidades de container query

As container queries também desbloqueiam unidades relativas ao contêiner em vez da viewport: cqw (1% da largura do contêiner), cqh, cqi (inline) e cqb (block). A tipografia fluida que escala com o seu contêiner vira uma única linha:

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

Container queries vs media queries

	Media query	Container query
Mede	Viewport / dispositivo	Ancestral dimensionado mais próximo
Configuração necessária	Nenhuma	container-type num pai
Melhor para	Layout no nível da página	Componentes reutilizáveis
Unidades	vw, vh	cqw, cqi, ...

Suporte dos navegadores

As size container queries são suportadas em Chrome, Edge, Firefox e Safari atuais. Elas não substituem as media queries — use media queries para a estrutura geral da página e container queries para componentes que precisam ser portáveis. As duas funcionam bem juntas.

A mudança mental é pequena, mas poderosa: pare de perguntar "qual é o tamanho da tela?" e comece a perguntar "quanto espaço este componente tem?". Essa única mudança é o que torna os componentes de um design system verdadeiramente encaixáveis em qualquer lugar.