Consultas de Contêiner CSS em 2026: Crie Componentes Responsivos Sem Pontos de Quebra de Viewport
Aprenda como as consultas de contêiner CSS fazem os componentes responsivos se adaptarem ao espaço disponível em vez do viewport do navegador. Crie cartões reutilizáveis, use contêineres nomeados e unidades de contêiner, e evite armadilhas comuns de layout e compatibilidade.
CSS Container Queries em 2026: Criar Componentes Responsivos Sem Pontos de Interrupção do Viewport
O design web responsivo tradicionalmente depende de media queries. Desenvolvedores escolhem pontos de interrupção do viewport e ajustam layouts para telefones, tablets e desktops. Isso ainda funciona bem para layouts de nível de página, mas componentes modernos frequentemente aparecem em muitos contextos: seções de largura total, barras laterais estreitas, dashboards, modais e grades.
Um card em um desktop de 1.440 pixels de largura pode ter ainda apenas 280 pixels disponíveis dentro de uma barra lateral. Um ponto de interrupção do viewport não pode descrever de forma confiável o espaço desse componente.
As CSS container queries permitem que os componentes respondam ao tamanho de um ancestral elegível, e não apenas do viewport. Isso as torna especialmente úteis em sistemas de design reutilizáveis, temas de blocos do WordPress, módulos do Joomla e construtores de páginas.
O que são CSS container queries?
Uma container query de tamanho avalia as dimensões de um contêiner ancestral designado. Um componente pode alterar seu layout interno quando o espaço disponível para ele ultrapassa um limite.
Por exemplo, um card pode exibir sua imagem acima do texto quando estreito, mas mover a imagem ao lado do texto quando seu contêiner tiver pelo menos 480 pixels de largura.
As media queries permanecem úteis para navegação em toda a página e preferências de dispositivo. As container queries resolvem o problema separado de responsividade em nível de componente.
Media queries vs. container queries: comparação visual e demonstração ao vivo
A ilustração compara as duas abordagens. Mova o controle deslizante para alterar a largura disponível do card. A demonstração usa uma CSS size container query real, não um alternador de layout controlado por JavaScript.
Media queries vs. container queries
Responds to browser viewport width.
Responds to available component space.
Try the 480px container breakpoint
A reusable card that adapts to the space available.
Read the guideHorizontal layout at 520px
Move the slider to change the container width. The card switches layout at 480px. On narrow screens the maximum width is limited to the available space.
O ponto de interrupção pertence ao design do componente, em vez de a uma categoria específica de dispositivo. Em uma tela de telefone estreita, a demonstração limita o contêiner à largura disponível do viewport.
Etapa 1: Criar um card semântico
Comece com um card que pode aparecer em uma lista de artigos, recomendação de produto ou índice de documentação:
<div class="card-container">
<article class="content-card">
<img class="content-card__image"
src="/images/example.webp"
alt="A laptop on a desk"
width="640" height="400">
<div class="content-card__body">
<h2>Building Better Web Components</h2>
<p>Learn how modern CSS makes layouts more reusable.</p>
<a href="/guide">Read the guide</a>
</div>
</article>
</div>
O elemento externo se tornará o contêiner de consulta. O artigo interno é o descendente cuja apresentação muda.
Essa distinção importa: uma container query de tamanho não estiliza o elemento consultado em si. Ela avalia um contêiner ancestral e estiliza descendentes correspondentes.
Etapa 2: Escrever um layout padrão robusto
Comece com um layout que permaneça utilizável sem container queries:
.card-container {
width: 100%;
}
.content-card {
display: grid;
grid-template-columns: minmax(0, 1fr);
gap: 1rem;
padding: 1rem;
border: 1px solid #d9dee5;
border-radius: 12px;
background: #fff;
}
.content-card__image {
display: block;
width: 100%;
height: auto;
aspect-ratio: 8 / 5;
object-fit: cover;
border-radius: 8px;
}
.content-card__body {
min-width: 0;
}
O layout padrão de imagem acima do texto funciona em espaços estreitos. A faixa de grade minmax(0, 1fr) e o min-width: 0 reduzem o risco de conteúdo longo transbordar.
Etapa 3: Declarar o contêiner de consulta
Use a propriedade container-type:
.card-container {
container-type: inline-size;
}
O valor inline-size habilita consultas de tamanho ao longo do eixo inline, que geralmente corresponde à largura em modos de escrita horizontais.
Você também pode encontrar:
.card-container {
container-type: size;
}
O valor size suporta ambos os eixos, mas introduz requisitos de contenção mais fortes. Para a maioria dos cards responsivos, o inline-size é um padrão mais prático.
A contenção importa porque os navegadores devem ser capazes de calcular o tamanho do contêiner sem dependências circulares com estilos de descendentes.
Etapa 4: Adicionar a regra responsiva
Agora altere o layout interno apenas quando o contêiner ancestral for suficientemente largo:

@container (min-width: 480px) {
.content-card {
grid-template-columns: 180px minmax(0, 1fr);
align-items: center;
}
.content-card__image {
height: 100%;
}
}
Uma barra lateral de desktop ampla com apenas 300 pixels de largura mantém o layout empilhado. Um card em uma coluna de conteúdo de 600 pixels se torna horizontal, mesmo que o viewport não seja especialmente largo.
Este é o benefício central: o componente responde ao seu próprio espaço disponível.
Etapa 5: Usar contêineres nomeados para layouts complexos
Em um modelo de dashboard ou CMS, um componente pode ter vários contêineres aninhados. Por padrão, uma consulta de tamanho encontra o ancestral elegível mais próximo.
Nomeie o contêiner pretendido quando precisar de mais controle:
.article-list-item {
container: article-card / inline-size;
}
@container article-card (min-width: 480px) {
.content-card {
grid-template-columns: 180px minmax(0, 1fr);
}
}
A abreviação container define tanto o nome quanto o tipo. A nomeação ajuda a impedir que um contêiner aninhado não relacionado se torne o alvo da consulta.
Etapa 6: Usar unidades relativas ao contêiner
O CSS inclui unidades de comprimento baseadas em um contêiner de consulta elegível:
| Unidade | Significado |
|---|---|
cqw |
1% da largura do contêiner |
cqh |
1% da altura do contêiner |
cqi |
1% do tamanho inline do contêiner |
cqb |
1% do tamanho de bloco do contêiner |
cqmin |
Menor entre cqi e cqb |
cqmax |
Maior entre cqi e cqb |
Para tipografia fluida de componentes:
.card-container {
container: article-card / inline-size;
}
.content-card h2 {
font-size: clamp(1.1rem, 4cqi, 1.8rem);
}
Ao contrário de vw, o cqi pode dimensionar o texto com o contêiner do componente. Sempre teste legibilidade, zoom do navegador e títulos longos traduzidos. Se nenhum contêiner elegível existir, as unidades relativas ao contêiner seguem o comportamento de fallback especificado, em vez de se tornarem inválidas.
Etapa 7: Adicionar aprimoramento progressivo
Mantenha o layout padrão empilhado e habilite condicionalmente o comportamento mais avançado:
.content-card {
display: grid;
grid-template-columns: 1fr;
}
@supports (container-type: inline-size) {
.card-container {
container-type: inline-size;
}
@container (min-width: 480px) {
.content-card {
grid-template-columns: 180px minmax(0, 1fr);
}
}
}
Navegadores sem o recurso relevante retêm um layout funcional. O fallback não precisa corresponder a todos os aprimoramentos; precisa permanecer legível e utilizável.
As container queries não substituem o Grid ou o Flexbox
O Grid e o Flexbox organizam elementos. As container queries determinam quando determinadas regras CSS devem ser aplicadas.
Por exemplo, uma coleção responsiva de cards pode precisar apenas do Grid:
.product-grid {
display: grid;
grid-template-columns:
repeat(auto-fit, minmax(min(100%, 240px), 1fr));
gap: 1.5rem;
}
Adicione container queries quando o design interno de cada card precisar mudar de acordo com sua largura atribuída. Evite introduzir contêineres de consulta onde o Grid ou Flexbox padrão já resolve o problema.
E quanto às container style queries?
As container queries também podem testar algumas condições de estilo computado, incluindo propriedades personalizadas em navegadores com suporte:
.feature-panel {
--panel-theme: dark;
}
@container style(--panel-theme: dark) {
.feature-panel__title {
color: white;
}
}
Isso ilustra a sintaxe; as style queries e recursos de consulta mais recentes têm detalhes distintos de suporte de navegador. O suporte para consultas de tamanho não garante suporte para todas as style queries, propriedades ou recurso de estado de rolagem mais recente. Verifique o recurso exato em relação às tabelas de compatibilidade atuais antes da implantação em produção.
Cinco erros comuns
1. Consultar o próprio tamanho de um elemento para estilizá-lo

Isso não funciona como pretendido:
.card {
container-type: inline-size;
}
@container (min-width: 480px) {
.card {
display: grid;
}
}
O contêiner consultado deve ser um ancestral do elemento estilizado. Introduza um wrapper externo ou mova a contenção para um ancestral adequado.
2. Esquecer de declarar um contêiner
Uma regra @container por si só não torna automaticamente o pai mais próximo um contêiner de tamanho elegível. Declare container-type: inline-size ou use a abreviação correspondente.
3. Reutilizar pontos de interrupção do viewport cegamente
Não use automaticamente 768px ou 1024px simplesmente porque esses números são familiares. Escolha um ponto de interrupção onde o conteúdo do componente realmente precise de um arranjo diferente.
4. Aplicar contenção em todos os lugares
A contenção altera o comportamento de dimensionamento. Muitos contêineres podem complicar a depuração, especialmente quando um elemento depende de descendentes para suas dimensões. Estabeleça contêineres intencionalmente.
5. Presumir que todo recurso de container query é igualmente suportado
As consultas de tamanho, as style queries e recursos mais recentes têm históricos de compatibilidade diferentes. Verifique a sintaxe exata que você planeja enviar.
Considerações de desempenho
As container queries são executadas no mecanismo CSS/layout do navegador. Elas podem eliminar alguns observadores de redimensionamento baseados em JavaScript e medições manuais do DOM.
Essa simplificação arquitetônica é útil, mas as container queries não garantem um site mais rápido. O custo de renderização depende da folha de estilo, complexidade do DOM, estrutura de layout e escolhas de contenção.
Meça o desempenho e evite camadas de consulta desnecessárias.
Aplicações práticas em WordPress e Joomla
Temas de blocos do WordPress: O mesmo bloco pode aparecer em uma seção de largura total, uma coluna estreita ou uma barra lateral. As container queries permitem que o bloco se adapte sem variantes separadas para desktop e mobile.
Modelos e módulos do Joomla: Um módulo pode ser atribuído a diferentes posições de modelo. Um layout baseado em componentes pode se adaptar à largura real do módulo, em vez de adivinhar com base no viewport.
Construtores de páginas: Editores movem frequentemente componentes entre colunas aninhadas. Regras baseadas em contêiner podem tornar esses componentes mais resilientes a mudanças de layout.
Dashboards: Painéis e widgets redimensionáveis podem ajustar seus layouts internos conforme o espaço disponível muda.
Quando ainda devo usar media queries?
As media queries permanecem adequadas para navegação dependente do viewport, estilos de impressão, preferências de movimento reduzido, capacidades de ponteiro e outras características do usuário/dispositivo.
Uma diretriz útil é media queries para a página; container queries para o componente. Não é uma regra absoluta, mas é uma maneira clara de dividir responsabilidades.
Como testar container queries
Teste o mesmo componente em uma área de conteúdo ampla, barra lateral estreita, grade e modal. Redimensione o contêiner, não apenas a janela do navegador.
Verifique transbordamento horizontal, distorção de imagem, títulos longos, zoom do navegador, conteúdo traduzido e modos de escrita da direita para a esquerda, quando relevante.
Use as ferramentas do desenvolvedor do navegador para inspecionar propriedades calculadas do contêiner e confirmar quais regras se aplicam. Teste em dispositivos estreitos reais, bem como em simulações de desktop.
Conclusão
As CSS container queries abordam uma limitação antiga do design responsivo baseado em viewport: o espaço disponível de um componente não corresponde necessariamente à largura do navegador.
Combinando contêineres de tamanho com Grid, Flexbox e fallbacks sensatos, os desenvolvedores podem criar componentes reutilizáveis que se adaptam naturalmente em temas, módulos, construtores de páginas e aplicativos.
Comece com um layout padrão funcional, declare apenas contêineres significativos, escolha pontos de interrupção com base no conteúdo e teste em vários contextos.
O design responsivo não é mais apenas sobre o tamanho da tela. Também é sobre o espaço disponível para cada componente.