Container Queries: Responsividade Baseada no Componente

Media queries sempre estilizaram elementos com base no tamanho da viewport, o que é um problema quando um componente precisa se adaptar ao espaço do seu container, não da tela inteira. As Container Queries resolvem isso: com @container, um elemento pode reagir ao tamanho do próprio pai, tornando componentes verdadeiramente reutilizáveis em qualquer layout.

Como funciona?

O processo tem duas partes: primeiro, um elemento precisa ser declarado como container com container-type. Depois, os filhos podem ser estilizados condicionalmente com @container:

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

@container card (min-width: 400px) {
    .card {
        display: flex;
        gap: 16px;
    }
}

Aqui, o .card muda para layout em linha somente quando o .card-wrapper que o contém tem pelo menos 400px de largura — independente do tamanho da janela do navegador.

Exemplo prático: card responsivo por container

.sidebar {
    container-type: inline-size;
}

.main {
    container-type: inline-size;
}

@container (min-width: 500px) {
    .produto {
        grid-template-columns: 120px 1fr;
    }
}

O mesmo componente .produto pode aparecer dentro da .sidebar (estreita, layout empilhado) ou da .main (larga, layout em grid), e vai se adaptar automaticamente ao espaço disponível em cada lugar, sem precisar de classes diferentes para cada contexto.

Container query units

Além do @container, o CSS ganhou unidades relativas ao container, como cqw, cqh, cqi e cqb, equivalentes às unidades de viewport, mas relativas ao container mais próximo:

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

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

Assim, o tamanho da fonte do título escala com a largura do container, e não da tela inteira.

Nomeando containers

Quando há containers aninhados, o container-name evita ambiguidade sobre a qual container a query se refere:

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

@container layout (min-width: 800px) {
    .grid {
        grid-template-columns: repeat(3, 1fr);
    }
}

Quando usar

Componentes de design system que precisam se adaptar ao espaço disponível, não à tela (cards, widgets, painéis).
Layouts com sidebar, onde o mesmo componente aparece em áreas de tamanhos diferentes.
Dashboards com widgets redimensionáveis pelo usuário.
Reduzir a necessidade de variantes de componente controladas por JavaScript ou por classes condicionais.

Cuidados

Um elemento não pode fazer @container em si mesmo — a query sempre olha para um container ancestral, então é comum precisar de um elemento "wrapper" extra só para declarar container-type. Além disso, definir container-type: inline-size cria um novo contexto de formatação no elemento, o que pode afetar como margin colapsa dentro dele.

Compatibilidade

O suporte a container queries de tamanho já é excelente em todos os navegadores modernos (Chrome, Edge, Firefox e Safari), o que torna seguro usar em produção na maioria dos projetos atuais.

caniuse

Conclusão

As Container Queries completam um espaço que faltava no CSS responsivo: estilizar com base no contexto real do componente, e não só no tamanho da tela. Isso torna possível criar componentes genuinamente reutilizáveis, que se adaptam sozinhos a qualquer lugar onde forem colocados.