CSS container queries: faça componentes responderem ao espaço disponível

A resposta direta: use CSS container queries quando um componente precisa adaptar seu layout à largura do espaço onde foi colocado, e não apenas à largura total da tela. Declare um container com container-type: inline-size e defina regras @container para reorganizar conteúdo, ajustar espaçamento ou tipografia. Media queries continuam úteis para a estrutura geral da página; container queries resolvem o comportamento local de módulos reutilizáveis, como cartões usados em grade e barra lateral.

Viewport e container respondem a perguntas diferentes

Uma media query avalia características do viewport, como largura da janela. Ela é adequada para decidir quando o menu principal muda, quando a navegação vira coluna ou quando a grade global passa de quatro colunas para uma. Já uma container query avalia o espaço do elemento ancestral declarado como container. O mesmo componente pode então reconhecer que está apertado dentro de uma barra, mesmo que a tela geral seja larga.

Essa distinção é importante em sites com módulos reutilizados. Um cartão de serviço pode aparecer na home em uma faixa ampla, em uma coluna lateral de artigo e numa grade de página de categoria. Com regras baseadas apenas no viewport, o componente pode continuar usando composição larga dentro de um espaço estreito. Uma regra local permite adaptar texto, imagem e ações ao espaço efetivamente disponível sem criar três componentes diferentes.

O recurso não substitui uma boa arquitetura de layout. Grid, Flexbox, unidades relativas e uma hierarquia clara continuam fundamentais. As queries entram quando a adaptação depende do tamanho do recipiente que o próprio componente recebe. Antes de acrescentá-las, desenhe quais estados são necessários e confirme o ponto em que o conteúdo deixa de caber confortavelmente; não escolha um breakpoint apenas por parecer popular em outro projeto.

A sintaxe moderna é amplamente suportada nos navegadores atuais, mas o projeto deve conhecer sua matriz de público e política de compatibilidade. A documentação do MDN mostra alternativas com Grid e Flexbox para contextos sem suporte. Uma estratégia robusta fornece primeiro um layout funcional e simples; as regras de container refinam a experiência em navegadores compatíveis, em vez de serem o único caminho para acessar conteúdo.

Declare o contexto que o componente pode consultar

Para uma query de largura, um ancestral precisa estabelecer contexto, por exemplo com container-type: inline-size. Isso permite consultar o eixo inline, que acompanha a direção do texto, e tende a ser a opção mais comum para cartões. O valor size também pode consultar dimensões nos eixos inline e block, mas introduz mais contenção e pode alterar como o tamanho intrínseco do elemento é calculado. Escolha a capacidade mínima necessária para o layout.

Um nome de container, como card ou sidebar, torna a regra explícita quando existem vários ancestrais possíveis. Sem nome, a condição é avaliada em relação ao container ancestral elegível mais próximo. Em componentes profundamente aninhados, nomear os contextos evita que uma query seja capturada por um wrapper inesperado. Documente nomes de forma semântica e mantenha a estrutura de CSS legível para quem vai dar manutenção.

A regra @container pode definir comportamento para o componente interno quando uma condição de largura for verdadeira. Exemplo conceitual: um cartão começa com imagem acima do texto; em um container mais largo, pode colocar imagem e conteúdo lado a lado. O limite deve refletir a quantidade de espaço necessária para texto, botão e imagem, não um modelo de telefone específico. Meça o conteúdo real, inclusive títulos longos e traduções.

Container query units, como cqi, permitem calcular valores relativos à dimensão do container elegível. Podem ser úteis em tipografia e espaçamento fluidos, mas não precisam ser usados em toda medida. Combine com limites mínimos e máximos quando o tamanho deve permanecer legível. Se não houver container elegível para uma unidade, o comportamento de fallback definido pela especificação entra em ação; teste componentes fora do contexto habitual.

Construa componentes previsíveis e reutilizáveis

Comece pela aparência base em um espaço estreito e funcional. Depois acrescente os estados que realmente melhoram leitura e interação quando o container cresce. Essa abordagem mobile-first não significa que o componente só exista para celular; é uma base que evita pressupor largura. Inclua títulos longos, imagens ausentes, botões com rótulos maiores, zoom e conteúdo traduzido nos testes. O layout precisa sobreviver a variações sem depender de uma medida fixa.

Evite que uma regra consulte a largura de um container cujo próprio tamanho depende da mudança de estilo aplicada aos filhos. Ciclos de tamanho podem produzir resultados instáveis ou impedir que a query opere como esperado. A contenção cria limites de layout para que o navegador avalie condições sem retroalimentação infinita. Se o container encolhe de modo inesperado, examine min-width, conteúdo intrínseco, grid tracks e o elemento que estabelece a contenção.

Não transforme todas as media queries em container queries automaticamente. Uma decisão global como ocultar navegação secundária em uma tela estreita pode depender do viewport e do dispositivo. Uma decisão sobre a apresentação de cada cartão deve depender do espaço local. Em algumas telas, as duas ferramentas trabalham juntas: media query ajusta grade externa, enquanto container query adapta os cartões no espaço que a grade lhes entrega.

Acessibilidade continua sendo requisito. Não esconda ações importantes no estado estreito, não dependa apenas de posição visual para ordem de leitura e preserve tamanho de toque e foco. Se a disposição muda, a ordem semântica do HTML continua clara para teclado e leitores de tela. Faça zoom, navegue por teclado, use conteúdo real e avalie contraste. Responsividade não é apenas evitar overflow; precisa conservar o entendimento e a possibilidade de completar tarefas.

Exemplo prático: cartão de serviço em várias áreas

Imagine um cartão de criação de sites mostrado em uma grade de três colunas, uma faixa de destaque na home e uma coluna lateral do blog. Com estilos ligados apenas à largura da tela, na página de artigo o cartão pode ficar espremido, com botão minúsculo e imagem comprimida. O componente recebe container-type: inline-size e consulta o espaço disponível. Em uma faixa ampla, divide imagem e texto; em espaço pequeno, empilha elementos e mantém a chamada fácil de ler.

A equipe testa um título curto e outro comprido, um botão com texto maior e a ausência de imagem. Confirma que o componente não cria barra horizontal, que os links seguem uma ordem semântica e que a tipografia não fica minúscula. A mesma implementação funciona no contexto de grade e da barra lateral, sem duplicar HTML ou espalhar regras condicionais no componente pai.

Quando o breakpoint parece inadequado, o time não tenta corresponder a uma família de aparelhos; mede a largura onde a composição começa a perder equilíbrio. Mantém Grid para definir o layout externo e usa @container para a mudança interna. O resultado é uma biblioteca de componentes mais consistente e fácil de mover entre páginas, embora não dispense testes com conteúdo, navegadores e acessibilidade.

A Open Leads oferece criação de sites e serviços de marketing; componentes flexíveis ajudam a manter páginas coerentes em diferentes áreas do site. Conheça os [serviços](/servicos), leia outros conteúdos no [blog](/blog) e veja informações da agência em [Google Partner](/google-partner). Para projetos em produção, use a compatibilidade atual dos navegadores do público e confirme o comportamento com ferramenta de inspeção.

Checklist de implementação

1. Decida se a regra depende do viewport ou da largura local do componente.
2. Declare o container mais próximo possível com container-type apropriado e nomeie contextos quando necessário.
3. Crie uma base funcional e adicione apenas estados que resolvam uma necessidade visível.
4. Teste texto longo, zoom, tradução, ausência de imagem, teclado e leitores de tela.
5. Evite depender do tamanho dos filhos para mudar ciclicamente o container consultado.
6. Mantenha Grid e Flexbox para a composição externa e forneça um caminho funcional para navegadores sem suporte.
7. Meça o ponto de quebra com conteúdo real e documente a regra para o design system.

Teste o contexto de uso, não só a página inicial

Componentes reutilizáveis aparecem em espaços que não existiam quando foram criados: um painel lateral pode surgir em telas grandes, um bloco pode ser embutido em um modal, ou um tema pode colocar o mesmo cartão dentro de uma coluna estreita. Container queries ajudam a lidar com essas composições, mas testes devem reproduzir o DOM real e as restrições dos pais. Um container pode ter largura mínima, padding ou overflow que faz a medida disponível diferir da largura visual. Inspecione o elemento que estabelece a query e verifique que a regra usa o ancestral esperado. Em design systems, documente quais componentes criam contextos e quais somente os consomem.

Perguntas frequentes

Container queries substituem media queries?

Não. Media queries continuam adequadas para layout global baseado no viewport; container queries adaptam elementos ao espaço de um contexto local.

Preciso declarar container-type?

Para consultar tamanho, sim: o ancestral precisa estabelecer o contexto apropriado, como inline-size para largura. Outras queries têm requisitos distintos.

Como escolher o breakpoint de @container?

Use a largura em que o conteúdo real precisa mudar para continuar confortável. Teste títulos, controles e traduções em vez de copiar um breakpoint de dispositivo.

Posso consultar qualquer elemento ancestral?

A regra usa um container elegível ancestral, normalmente o mais próximo se nenhum nome for especificado. Nomear contextos ajuda quando a estrutura é mais complexa.

O que acontece em navegadores sem suporte?

Mantenha um layout base que continue utilizável. Grid, Flexbox e media queries podem fornecer uma composição funcional como fallback.

Quer transformar tráfego em oportunidades reais? A Open Leads integra mídia paga, mensuração e criação de sites focados em conversão. Conheça os serviços da Open Leads.

Fontes consultadas

Consulte os materiais originais usados na pesquisa deste artigo.

• CSS container queries — MDN Web Docs
• Using container size and style queries — MDN Web Docs
• Container queries and units in action — web.dev
• CSS Containment Module Level 3 — W3C