# Pare de tratar container queries como media queries
> Container queries não funcionam como media queries. Veja a diferença, quando usar cada uma e os efeitos colaterais que pegam quem começa a usá-las.
URL: https://dpw.dev/css/container-queries-nao-sao-media-queries/
Publicado em: 2026-10-08
Categoria: css
Tags: layout, web-design-responsivo
Autor: Tárcio Zemel
As **container queries** têm suporte amplo nos navegadores e, mesmo assim, continuam pouco usadas e mal compreendidas. A seguir, como elas diferem das media queries, quando usar cada uma e como permitem que componentes reutilizáveis se adaptem ao espaço em que aparecem, sem depender da largura da tela.
> Artigo baseado em [Stop Treating CSS Container Queries Like Traditional Media Queries](https://smashingmagazine.com/2026/09/stop-treating-css-container-queries-traditional-media-queries/).
O autor, Victor Ayomipo, admite que perdeu a notícia quando as CSS Container Queries chegaram aos navegadores. E, quando finalmente ouviu falar delas, o primeiro pensamento foi: *"Para que exatamente eu preciso disso, se as media queries já existem?"*
Ele não se orgulha dessa reação, sabendo o que sabe hoje, mas foi reconfortante descobrir que não estava sozinho. Na verdade, tem muita gente na mesma situação.
O que intriga é que container queries não são um recurso novo: o suporte nos navegadores está em torno de 94%. E, ainda assim, pouquíssima gente as usa de fato.
Logo no início, já mostramos, na prática, como é o funcionamento em nosso vídeo **Container Queries para Web Design Responsivo de Verdade**:
[Vídeo no YouTube](https://www.youtube.com/watch?v=narcAe-Q7OY)
Segundo a pesquisa State of CSS, 86% dos devs conhecem container queries, mas só 41,4% realmente as utilizam. Pesquisas podem ter viés e não representar a área inteira, mas essa certamente é o melhor indicador disponível.
Kevin Powell também falou disso na SmashingConf Amsterdam 2026: **a adoção de container queries tem sido péssima**.
E isso é muito estranho, considerando que a capacidade de componentes se adaptarem ao tamanho do container externo esteve no topo de tantas listas de desejos de CSS ao longo dos anos.
Aqui mesmo no blog, em 2018, o assunto apareceu em Responsive Components: uma solução para container queries, quando o suporte nativo ainda nem existia.
Mais interessante do que saber quantas pessoas usam container queries é saber *como* elas as usam. Não dá para falar por todo mundo, mas, pelo que se vê por aí (e nas primeiras tentativas do Victor também), muita gente está usando container queries *do jeito errado*.
No fim das contas, o uso incorreto vem daquela primeira impressão: **à primeira vista, elas parecem exatamente media queries**. E, como parecem parecidas, é fácil presumir que servem a propósitos semelhantes e funcionam do mesmo jeito.
Não é o caso.
> **Nota:** **Observação:** o foco deste artigo são as container queries de *tamanho*, ou seja, uma técnica de design responsivo que reage ao tamanho de um container específico. Também existem as container queries de *estilo*, que reagem aos estilos computados de um container (e eram experimentais quando o artigo foi escrito). Para se atualizar sobre elas, vale ler o texto de Juan Diego na Smashing Magazine, que examina possíveis casos de uso, e o post sobre CSS Style Queries aqui do blog.
## Media queries olham para fora
O viewport é um substituto. Sempre foi. Foram as media queries que criaram a ilusão de que a largura da tela, sozinha, é responsável por como apps responsivos se adaptam ao ambiente.
Vale a pergunta: ao escrever `@media`, o que se está perguntando ao navegador?
```css
@media (min-width: 1024px) {
.card {
display: flex;
}
}
```
Para a maioria dos devs, a pergunta é: *qual é a largura da tela agora?* Só isso.
As media queries respondem isso muito bem, mas o que acontece quando esse componente `.card` é colocado numa célula de grid com `300px` de largura, numa tela de desktop de `1920px`?
A media query não se importa: ela faz o trabalho dela. O viewport continua com `1920px`, então `min-width: 1024px` dispara e os estilos da query são aplicados, mesmo que o card só tenha `300px` de espaço para trabalhar. No fim, tudo dentro do card se deforma, transborda ou fica espremido.
> "Media queries são burras. Não burras como conceito, mas burras no sentido de que não sabem muita coisa. Na verdade, a maioria das pessoas presume que elas sabem mais do que realmente sabem."
>
> Kevin Powell
É comum pensar no design responsivo apenas como um sistema para atualizar layouts de página inteiros, como passar de duas colunas numa tela grande para uma coluna só numa tela pequena.
## Container queries olham para dentro
As container queries são mais espertas que isso. Elas fazem os layouts responsivos dependerem mais do que acontece **dentro** de um componente do que do contexto externo, que não faz ideia do conteúdo do componente. A pergunta passa a ser algo como: *"Quanto espaço está disponível para mim neste lugar específico, agora?"*
Este é o mesmo exemplo de card da seção anterior, agora com uma container query:
```css
.card-wrapper {
container-name: card;
container-type: inline-size;
}
@container card (min-width: 450px) {
.card {
display: flex;
flex-direction: row;
}
}
```
Isso muda tudo. O card não é influenciado pelo viewport: a única preocupação dele é saber se o wrapper pai do componente `.card` tem pelo menos `450px` de espaço inline (ou seja, horizontal, num modo de escrita da esquerda para a direita).
Se a condição for verdadeira, o componente fica na horizontal; se não, volta ao display padrão, `block`.
[Exemplo no CodePen](https://codepen.io/smashingmag/pen/RNpoLNX)
Na figura abaixo, o mesmo card está em duas colunas de uma página: a principal e uma sidebar de `300px`. Troque a query e arraste sobre a figura para mudar a viewport. Com `@media`, os dois cards mudam juntos em `1024px`; com `@container`, cada um olha só para a própria coluna.
> **Figura interativa:** um gabarito de bancada em que a distância entre duas paredes é a viewport; a parede da direita leva a baia de uma sidebar de 300px, e cada baia tem o mesmo card, que fica em linha ou empilhado conforme a marca de 1024px da media query ou a de 450px da container query de cada baia. Disponível na versão HTML desta página.
## Layouts "macro" vs. layouts "micro"
Um jeito bem interessante de distinguir `@media` e `@container` é pelo **tipo de layout**.
As media queries servem para o layout "macro": elas olham para fora.
São coisas como a estrutura da página, o header que ocupa a janela inteira, o footer, o grid principal, as preferências do sistema (`prefers-color-scheme`) e as capacidades do dispositivo (telas touch). Ou seja, tudo o que vale para a estrutura da página como um todo.
Já as container queries servem para os layouts "micro", isto é, a maior parte do que vive dentro do layout "macro". Elas entram em cena quando um conteúdo precisa caber, de forma responsiva, em qualquer espaço que receber. Os componentes que vêm à mente são cards, widgets, formulários, navegação e assim por diante.
Em outras palavras, pense em **"layout da página" vs. "layout do componente"**. É a mesma virada descrita em O novo web design responsivo, quando container queries ainda eram só uma proposta.
Um elemento não deveria virar "tamanho tablet" num passe de mágica só porque a largura passou de um limite abstrato como `768px`. Ele deveria trocar de layout quando tiver espaço suficiente para isso, seja num viewport de celular, seja dentro de uma sidebar no desktop.
Ainda não se convenceu? Sabia que existem mais de 2.300 tamanhos de viewport diferentes na web atual? Dá para dar conta de todos eles?
> Não se trata de odiar media queries. É que, nesta era de responsividade e reuso de componentes, a lógica de layout está mais perto do container do que do viewport. Ao pensar em containers e componentes, quem determina o layout é o conteúdo, não o viewport.
É assim que deveria ser.
## Exemplo: tipografia fluida dentro de um componente
Tipografia responsiva é um bom exemplo de algo para o qual muita gente sempre recorreu às media queries. Como existem unidades de CSS relativas ao tamanho do viewport (`vw`, `vh` e assim por diante), as media queries parecem ótimas para ajustar o tamanho da fonte de acordo com a tela do usuário.
```css
.card-title {
font-size: clamp(100%, 1rem + 2vw, 24px);
}
```
Isso funciona até o mesmo componente ser levado para outro contexto, como uma sidebar, onde o viewport é totalmente irrelevante. Como a responsividade foi amarrada ao ponto de referência errado, a tipografia escalonada pode ficar grande ou pequena demais.
As container queries têm unidades próprias (`cqi`, `cqw`, `cqb`, entre outras). Dá para levar os componentes responsivos além combinando essas unidades com a função `clamp()` do CSS, usada para tipografia fluida que escala com o componente, e não com o viewport:
```css
.card-title {
font-size: clamp(1rem, .5rem + 3cqi, 2rem);
}
```
[Exemplo no CodePen](https://codepen.io/smashingmag/pen/rayWGVd)
Com isso, todo o código fica contido no container específico daquele elemento.
## Exemplo: detectando a quebra de linha do flexbox
Curiosamente, as container queries conseguem, de certa forma, detectar o estado do layout interno de um componente. Não é à prova de falhas, mas é algo que as media queries simplesmente não conseguem fazer.
Elas só observam a janela do navegador e são estruturalmente cegas a eventos internos de layout, como o momento em que itens flex quebram para uma nova linha. Vale investigar isso.
O flexbox é excelente para quebrar conteúdo em linhas (`flex-wrap: wrap`): os itens flex passam automaticamente para novas linhas quando o flex container não tem mais espaço para acomodá-los numa linha só. Mas o CSS, sozinho, não consegue saber quando essa quebra acontece.
Não existe uma pseudo-classe `:wrapped` nem uma media query como `@media (flex-wrapped: true)` que resolva isso.
Media queries só observam a janela do navegador, então não enxergam mudanças internas. E é basicamente isso que a quebra do flex é: uma mudança de estado na largura do próprio item.
Por exemplo, num menu horizontal alinhado com flexbox em que os itens devem mudar de estilo só quando quebram de linha, o caminho seria JavaScript, usando `ResizeObserver` para obter essa informação.
Mas, aninhando container queries dentro dos itens flex, dá para chegar a uma solução alternativa sem JavaScript, graças a uma técnica ensinada por Kevin Powell. A ideia central é deixar o item flex com `flex-grow: 1` ao consultar o inline size do container.
[Exemplo no CodePen](https://codepen.io/smashingmag/pen/rayWGVd)
A lógica funciona assim:
- Quando há espaço suficiente, os dois itens (`.flex-item`) ficam lado a lado, cada um com exatamente metade da largura do container pai.
- Quando o espaço é limitado, o segundo item quebra para a linha seguinte.
- Como `flex-grow` está ativo em cada item, os itens quebrados se esticam para preencher a maior parte da largura do pai.
- Se o item também é um container, ele detecta o súbito aumento de largura e a query dispara.
```css
/* O pai flex */
.flex-layout {
display: flex;
flex-wrap: wrap;
}
/* Registra um item flex como container */
.flex-item {
container-type: inline-size;
flex: 1 1 390px; /* Cresce para preencher o espaço, quebra em 390px */
}
/* Estilos padrão do card (estreito / lado a lado) */
.card {
display: flex;
flex-direction: column;
background: #f4f4f4;
}
/* Quando há espaço para uma linha inteira */
@container (min-width: 600px) {
.card {
flex-direction: row;
align-items: center;
background: #e2f0d9;
}
}
```
Funciona. Conforme o pai encolhe e os cards quebram em duas linhas, o item do card se expande, a container query dispara e aplica os estilos necessários.
[Exemplo no CodePen](https://codepen.io/smashingmag/pen/ByWQwLz)
## Container queries também têm efeitos colaterais
Container queries, como tudo, têm alguns efeitos colaterais e ressalvas que merecem atenção antes de recorrer a elas.
### 1. Um container exige um wrapper extra
Container queries precisam de algo parecido com uma relação pai-filho para funcionar como esperado. Imagine esta marcação:
```html
```
Não dá para consultar o próprio componente `.card` para ajustar o `.card-content`, assim:
```css
/* NÃO FUNCIONA */
.card {
container-name: card;
container-type: inline-size;
}
@container card (min-width: 400px) {
.card {
display: flex;
}
}
```
Isso não funciona porque um container não pode consultar a si mesmo. No último exemplo, consulta-se um container `card` e depois tenta-se ajustar o display desse mesmo container com base no tamanho dele. É um loop infinito.
Em vez disso, é preciso um wrapper adicional que torne o `.card` descendente do container:
```html
```
A partir daí, dá para consultar o container `.cards` e ajustar o layout do `.card`:
```css
.cards {
container-name: cards;
container-type: inline-size;
}
@container cards (min-width: 400px) {
.card {
display: flex;
}
}
```
Nas media queries isso não importa, porque `@media` não se preocupa com qual elemento é estilizado dentro do bloco: a única preocupação é o viewport, que está sempre disponível. Então basta colocar uma condição em qualquer elemento e pronto.
### 2. Consultar o `size` de um container pode colapsar o layout
Isso acontece ao consultar o `size` do container (ou seja, o tamanho de bloco, vertical) em vez do `inline-size`:
```css
/* Colapsa para 0px mesmo com conteúdo dentro */
.hero-banner {
container-type: size;
}
```
Por quê? Porque o navegador calcula as dimensões do container sem olhar para os filhos. Se o `.hero-banner` não receber uma `height` explícita (ou `min-height`, ou `aspect-ratio`), o navegador define a altura como `0px`.
Por isso, costuma ser melhor consultar um container pelo `inline-size`. A não ser que seja realmente necessário consultar o tamanho de bloco do container.
Media queries não são afetadas por isso, já que tratam a altura do mesmo jeito que `@media (min-height: ...)` faz: perguntam ao viewport e seguem em frente.
### 3. Queries não aceitam custom properties
Outra limitação das container queries: não dá para consultar o valor de uma custom property.
```css
:root {
--breakpoint-lg: 1600px;
}
/* NÃO FUNCIONA */
@container (min-width: var(--breakpoint-lg)) {
/* ... */
}
```
Isso acontece porque custom properties dependem de valores que descem em cascata pela árvore do DOM. Uma container query que depende de uma custom property poderia alterar essa mesma custom property. E isso pode ficar complicado rapidamente:
```css
:root {
--breakpoint-lg: 1600px;
}
/* NÃO FUNCIONA */
@container cards (min-width: var(--breakpoint-lg)) {
.card {
--breakpoint-lg: 1000px;
}
}
```
## Quando usar media queries e quando usar container queries
Isso não significa que algum projeto deva trocar `@media` por `@container` em tudo. As media queries continuam tendo um papel importante em layouts responsivos. A questão é entender a separação de responsabilidades.
Container queries fazem sentido quando um componente é usado em mais de um contexto de layout. Por exemplo, um elemento `.card` pode viver num grid de largura total ou numa sidebar mais estreita.
Nesse caso, o ideal é que o conteúdo do componente determine quando ele se ajusta, e não uma media query olhando para o viewport externo.
Já as media queries servem para quando um componente existe apenas no nível da página. Seria algo como uma navegação principal que fica sempre no topo da página.
Ela é influenciada diretamente pelo tamanho do viewport, então o viewport é uma referência confiável para saber quando a navegação precisa se ajustar. De novo: tudo se resume a layout "macro" versus layouts "micro".
Este é o diagrama sugerido para decidir qual tipo de query usar:
## Conclusão
No fim das contas, o motivo central de container queries parecerem tão semelhantes a media queries é simplesmente a familiaridade. Elas não são exatamente "novas", mas são bem menos compreendidas e adotadas que as media queries.
Só que as media queries têm suas próprias limitações; se não tivessem, não haveria necessidade de container queries para preencher essas lacunas.
O que se tem é um recurso mais eficaz para detectar quando o contexto de um componente específico muda, e um meio de ajustar os estilos com base no conteúdo dele, como deve ser quando esse componente pode existir em vários contextos. (gg, yk)
## Perguntas frequentes
### Preciso de fallback para navegadores sem suporte a container queries?
Na maioria dos projetos, não. As container queries de tamanho funcionam em todos os navegadores principais desde fevereiro de 2023, e o [MDN as marca como Baseline amplamente disponível](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/container-type). Mesmo assim, vale escrever os estilos de fora do `@container` como uma versão que funciona sozinha: um navegador que ignore a regra mostra o componente nesse estado padrão, sem quebrar.
### O `inline-size` também pode colapsar o layout, como acontece com o `size`?
Pode, quando a largura do elemento depende do conteúdo. Com `container-type: inline-size`, o navegador [calcula a largura do container ignorando os filhos](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/container-type). Num elemento de bloco, que estica até a largura do pai, ou num item de grid ou flex que recebe o tamanho do layout, nada muda. Já num `inline-block`, num `float` ou num `position: absolute` sem largura definida, o container encolhe até zero. A saída é dar uma largura a ele ou registrar como container um elemento em volta, [como mostra Ahmad Shadeed](https://ishadeed.com/article/css-container-query-guide/).
### As unidades `cqi` funcionam sem nenhum container definido?
Funcionam, mas medem outra coisa. Sem um container entre os ancestrais, `cqi` e as demais unidades de container passam a valer como as unidades de viewport pequeno (`svi`, `svw` e afins), [segundo o MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Containment/Container_queries). O `clamp()` do [exemplo de tipografia fluida](#exemplo-tipografia-fluida-dentro-de-um-componente) continua valendo, só que acompanhando a tela, sem nenhum erro no console. Se a fonte não reage ao componente, confira se o wrapper dele tem `container-type`.
### Dá para usar a sintaxe de intervalo, como `width >= 400px`, numa container query?
Dá. A condição do `@container` segue a mesma sintaxe das media queries de tamanho: `(width >= 400px)` equivale a `(min-width: 400px)`, e dá para delimitar uma faixa com dois limites. Também valem `and`, `or` e `not`, com uma restrição: o `not` aparece uma vez só e não se mistura com os outros dois ([referência do `@container` no MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@container)).
```css
@container cards (400px <= width < 800px) {
.card {
display: flex;
}
}
```
## Teste seus conhecimentos
**Pergunta 1.** Numa tela de `1920px`, o `.card` está numa célula de grid com `300px` de largura. O que este CSS faz com ele?
```css
@media (min-width: 1024px) {
.card {
display: flex;
}
}
```
- O card continua `block`, porque só tem `300px`
Esse seria o resultado de uma container query consultando o wrapper do card. A media query não sabe quanto espaço o card tem.
- O card vira flex só quando a célula do grid passar de `1024px`
Em `@media`, `min-width` é sempre a largura do viewport. A condição não olha para a célula nem para nenhum outro elemento.
- O card vira flex, mesmo espremido em `300px` **(correta)**
A media query só pergunta a largura do viewport, e `1920px` passa de `1024px`. O espaço que sobra para o card não entra na conta.
O card vira flex. Media queries olham para fora: a pergunta que `@media` faz é sobre o viewport, então o card recebe o layout de tela grande mesmo sem espaço para ele. Para o card reagir ao espaço que tem, a consulta precisa ser feita a um container.
**Pergunta 2.** Por que este CSS não deixa o `.card` em flex quando ele passa de `400px`?
```css
.card {
container-type: inline-size;
}
@container (min-width: 400px) {
.card {
display: flex;
}
}
```
- Falta dar um `container-name` ao `.card`
O nome é opcional. Sem ele, `@container` consulta o container ancestral mais próximo, que é justamente o que falta aqui.
- Falta um wrapper: o `.card` não consulta a si mesmo **(correta)**
Um container só responde pelos descendentes. Para mudar o `.card`, o container tem de ser um elemento em volta dele.
- `min-width` não funciona com `container-type: inline-size`
Funciona: `inline-size` define qual dimensão do container pode ser consultada, e `min-width` é uma condição sobre essa dimensão.
Falta o wrapper. Um container não pode consultar o próprio tamanho para mudar o próprio layout (seria um ciclo), então as regras dentro de `@container` só valem para os descendentes dele. Com um `.cards` em volta, registrado como container, a mesma query passa a funcionar para o `.card`.
**Pergunta 3.** Um `.hero-banner` sem `height` definida recebe `container-type: size`. O que acontece com a altura dele?
- Colapsa para `0px`, mesmo com conteúdo dentro **(correta)**
Com `size`, o navegador calcula as duas dimensões do container sem olhar para os filhos. Sem `height`, `min-height` ou `aspect-ratio`, a altura fica zerada.
- Continua do tamanho do conteúdo
Isso vale para `inline-size`, que só isola a largura. `size` isola também a altura, e aí o conteúdo deixa de contar.
- Passa a ter a altura do viewport
Nada no container recorre ao viewport. A altura vem só do que foi declarado no próprio elemento.
A altura colapsa para `0px`. Por isso, na maioria dos casos, a escolha é `container-type: inline-size`, que deixa a altura seguir o conteúdo. `size` só compensa quando é preciso consultar a altura do container, e aí ele precisa de uma altura explícita.
**Pergunta 4.** Quais destes casos pedem `@container` em vez de `@media`? *(marque todas as corretas)*
- Trocar as cores quando o sistema está em dark mode
Preferência do sistema vale para a página toda: é caso de `@media (prefers-color-scheme: dark)`.
- Um card que aparece tanto no grid principal quanto numa sidebar estreita **(correta)**
É um componente reutilizado em lugares com espaços diferentes, e o viewport não diz nada sobre o espaço de cada um.
- Ajustar a navegação principal, que fica sempre no topo da página
Ela só existe no nível da página e depende da largura da tela. É layout macro, terreno de `@media`.
- Um título que deve crescer junto com o componente em que está **(correta)**
Unidades como `cqi` dentro de `clamp()` escalam com o container. Com `vw`, a fonte acompanharia a tela.
As corretas são o card e o título. Media queries cuidam do layout macro: a estrutura da página e as preferências e capacidades do dispositivo. Container queries cuidam do layout micro, os componentes que precisam caber em qualquer espaço que recebam.
---
Fonte: [dpw - desenvolvimento para web](https://dpw.dev/) (pt-BR).
Guia para agentes: https://dpw.dev/llms.txt
Índice completo: https://dpw.dev/sitemap-index.xml
Feed: https://dpw.dev/rss.xml