Layout responsivo com Tailwind na prática: container queries e estratégia de breakpoints

Introdução

Olhe para aquele componente de card no monitor.

Na página inicial, ele está perfeito: imagem à esquerda, texto à direita e um espaçamento confortável. Mas basta copiá-lo para a barra lateral para o layout inteiro desabar como uma folha de papel amassada. A imagem fica espremida, e as quebras de linha transformam o texto em uma bagunça.

Como esse negócio deveria saber qual formato adotar?

O problema está aqui: o design responsivo tradicional só reconhece a “viewport”. O componente muda de acordo com o tamanho da janela do navegador, mas não sabe qual é a largura do contêiner em que foi colocado. É como alguém que mora em uma casa enorme e, de repente, vai parar em um apartamento de 30 metros quadrados sem ter ideia de como organizar os móveis.

As container queries do Tailwind existem para resolver justamente esse problema. Elas permitem que o componente “perceba” o tamanho do contêiner ao redor, em vez de olhar apenas para a janela do navegador.

Neste artigo, vamos tratar das duas partes do layout responsivo com Tailwind que mais costumam causar problemas: como escolher uma estratégia de breakpoints e como usar container queries. Incluí bastante código prático, porque ler a documentação cem vezes ainda ensina menos do que executar um exemplo por conta própria.

A evolução do design responsivo: da viewport ao contêiner

Media queries: os velhos problemas da abordagem tradicional

Para falar a verdade, usei media queries durante anos e sempre achei que funcionavam muito bem. Isso mudou quando precisei colocar o mesmo componente de card em três lugares completamente diferentes: o fluxo de cards da página inicial, uma área de recomendações na barra lateral e uma lista dentro de um modal.

Foi aí que o problema das media queries ficou evidente.

Elas avaliam a largura da viewport, ou seja, o tamanho da janela do navegador. Mas o que realmente interessa ao componente deveria ser outra coisa: qual é a largura do seu pai — digo, do contêiner pai.

Veja este exemplo:

/* Media query tradicional */
@media (min-width: 768px) {
  .card {
    flex-direction: row;
  }
}

Esse código diz que, quando a janela do navegador ultrapassar 768px, o card deve adotar um layout horizontal.

Mas e se a viewport tiver 1200px e a barra lateral tiver apenas 280px de largura? O card ainda mudará para o layout horizontal e ficará todo espremido naquele espaço estreito.

O resultado que vi na época parecia um pé tamanho 44 sendo forçado dentro de um sapato 38.

Container queries: uma mudança de perspectiva

As container queries partem de outra pergunta. Em vez de “qual é o tamanho da janela do navegador?”, elas perguntam “qual é o tamanho do meu contêiner?”.

/* Container query */
@container (min-width: 400px) {
  .card {
    flex-direction: row;
  }
}

O significado desse código é completamente diferente: o card muda para o layout horizontal quando a largura do contêiner ultrapassa 400px.

Talvez você esteja pensando: isso faz tanta diferença assim?

Faz — e muita.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

O mesmo componente de card pode ficar em uma área de conteúdo com 600px de largura e usar o layout horizontal sem nenhum problema. Se for colocado em uma barra lateral de 280px, ele muda automaticamente para uma pilha vertical. Não é preciso criar dois componentes, passar props nem escrever uma coleção de condicionais.

Finalmente, o componente se torna verdadeiramente reutilizável.

Suporte dos navegadores

As container queries passaram a ter amplo suporte dos principais navegadores por volta de 2023. Até 2024, as Container Size Queries já contavam com mais de 90% de cobertura: Chrome, Firefox, Safari e Edge ofereciam suporte ao recurso.

Se o seu projeto ainda precisar funcionar em navegadores antigos, talvez seja melhor esperar. Mas, sinceramente, a maioria dos projetos atuais já deve conseguir usar o recurso.

Entendendo o sistema de breakpoints do Tailwind CSS

Antes de falar sobre container queries, precisamos entender bem o sistema de breakpoints do Tailwind. Afinal, ele é a base de tudo.

Quais são os breakpoints padrão

Por padrão, o Tailwind oferece cinco breakpoints:

Não tem problema se você não memorizar esses números; com o uso, eles acabam ficando familiares. O importante é entender que os breakpoints do Tailwind são de largura mínima. Em outras palavras, md:flex-row significa: “aplique flex-row quando a viewport tiver 768px ou mais”.

Mobile first: comece pelos estilos das telas pequenas

O sistema de breakpoints do Tailwind segue a abordagem mobile first. O que isso significa?

Ao escrever os estilos, o padrão corresponde ao celular. Depois, você usa os breakpoints para adicionar melhorias progressivas.

<!-- Abordagem mobile first -->
<div class="flex flex-col md:flex-row lg:gap-8">
  <!-- Celular: empilhamento vertical -->
  <!-- Tablet (md): disposição horizontal -->
  <!-- Desktop (lg): espaçamento maior -->
</div>

A vantagem dessa abordagem é que os estilos evoluem do simples para o complexo, camada por camada. Se alguém acessar com um celular antigo, carregará apenas os estilos mais básicos, o que também ajuda no desempenho.

Na abordagem oposta, desktop first, seria preciso escrever vários breakpoints invertidos, o que complica bastante. Por isso, costumo trabalhar diretamente com mobile first, a menos que o projeto tenha uma necessidade específica.

Quando criar breakpoints personalizados

Na maioria dos projetos, os breakpoints padrão são suficientes. Mas há exceções.

Em um sistema administrativo que desenvolvi, por exemplo, os breakpoints definidos pela designer não coincidiam em nada com os valores padrão do Tailwind. Ela definiu 480px, 720px, 960px e 1200px.

Nesse caso, foi preciso alterar o tailwind.config.js:

// tailwind.config.js
module.exports = {
  theme: {
    screens: {
      'xs': '480px',   // Adiciona um breakpoint menor
      'sm': '640px',
      'md': '720px',   // Substitui o valor padrão
      'lg': '960px',
      'xl': '1200px',
    }
  }
}

Outra necessidade comum é criar um breakpoint menor que sm, voltado a telas de celular bem pequenas. Basta adicionar um xs:

screens: {
  'xs': '475px',   // Novo breakpoint
  'sm': '640px',
  // ... os demais permanecem com os valores padrão
}

Como nomear breakpoints de forma semântica

Já tive problemas com isso.

Certa vez, dei aos breakpoints os nomes mobile, tablet e desktop. Parece intuitivo, não é? Só que o projeto depois passou a contemplar dispositivos dobráveis e telas automotivas, e esses nomes deixaram de fazer sentido.

Aprendi a lição e passei a usar indicadores de tamanho, como sm, md e lg. Eles não estão vinculados a um tipo específico de dispositivo; representam apenas uma escala de tamanhos. Assim, mesmo que surja um novo tipo de tela no futuro, o nome do breakpoint não ficará ultrapassado.

Container queries na prática: faça o componente “perceber” o espaço

Agora chegamos ao ponto principal. Nesta seção, vou mostrar com código real como usar container queries.

Primeiro passo: defina o contêiner

O primeiro passo é informar ao navegador que determinado elemento é um “contêiner”.

No Tailwind, basta adicionar a classe @container:

<!-- Contêiner pai -->
<div class="@container">
  <!-- Os elementos filhos podem ajustar o estilo conforme o tamanho do contêiner -->
  <div class="flex flex-col @sm:flex-row">
    ...
  </div>
</div>

Depois que recebe @container, essa div se torna um contêiner de consulta. Seus elementos filhos podem usar breakpoints de contêiner como @sm e @md nos estilos.

Quais são os breakpoints de contêiner

Os breakpoints de contêiner oferecidos pelo Tailwind são um pouco diferentes dos breakpoints de viewport:

Percebeu? Os valores dos breakpoints de contêiner são muito menores que os de viewport. Isso faz sentido: o contêiner está aninhado dentro da página e não pode ser mais largo que a própria viewport.

Exemplo prático 1: componente de card adaptável

Vamos criar um componente de card que possa ser usado de verdade. Os requisitos são:

• Contêiner com menos de 384px: empilhamento vertical e imagem ocupando toda a largura
• Contêiner com 384px ou mais: disposição horizontal e imagem com largura fixa
• Contêiner com 512px ou mais: imagem maior e mais linhas de texto

<!-- Contêiner pai: informa ao navegador que este é um contêiner de consulta -->
<div class="@container p-4">
  <!-- Componente de card -->
  <article class="flex flex-col @sm:flex-row @lg:gap-6 bg-white rounded-lg shadow">
    <!-- Imagem: largura ajustada conforme o contêiner -->
    <img
      src="https://example.com/image.jpg"
      alt="Imagem do artigo"
      class="w-full @sm:w-32 @lg:w-48 h-48 @sm:h-32 @lg:h-36 object-cover rounded-t-lg @sm:rounded-l-lg @sm:rounded-tr-none"
    />

    <!-- Área de conteúdo -->
    <div class="p-4 @sm:py-2 @lg:py-4 flex-1">
      <h3 class="text-base @lg:text-lg font-semibold mb-2">
        Introdução às container queries do Tailwind
      </h3>
      <p class="text-sm text-gray-600 line-clamp-2 @lg:line-clamp-3">
        Este artigo mostra como usar as container queries do Tailwind CSS para criar componentes com layouts realmente responsivos...
      </p>
      <div class="mt-3 flex items-center text-xs text-gray-400">
        <span>2026-03-27</span>
        <span class="mx-2">·</span>
        <span>5 min de leitura</span>
      </div>
    </div>
  </article>
</div>

Coloque esse código em uma barra lateral com 280px de largura e o card adotará automaticamente um layout vertical compacto. Coloque-o em uma área de conteúdo de 600px e ele se transformará em um layout horizontal mais espaçoso.

Sem alterar uma linha de código.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Exemplo prático 2: barra de navegação reutilizável

A barra de navegação é um dos cenários que melhor demonstram o valor das container queries.

O mesmo componente de navegação pode aparecer em:

• Uma barra de navegação superior, geralmente larga
• Uma barra lateral, que pode ser estreita
• Um menu lateral deslizante em dispositivos móveis

<!-- Componente de navegação -->
<nav class="@container">
  <ul class="flex flex-col @lg:flex-row @lg:items-center gap-2 @lg:gap-6">
    <li>
      <a href="/" class="block py-2 px-3 rounded hover:bg-gray-100">
        Início
      </a>
    </li>
    <li>
      <a href="/posts" class="block py-2 px-3 rounded hover:bg-gray-100">
        Artigos
      </a>
    </li>
    <li>
      <a href="/about" class="block py-2 px-3 rounded hover:bg-gray-100">
        Sobre
      </a>
    </li>
  </ul>
</nav>

Quando o contêiner tiver 512px ou mais, ou seja, atingir @lg, os itens de navegação passarão automaticamente para a disposição horizontal.

Assim, você pode reutilizar o mesmo componente de navegação em diferentes lugares sem escrever estilos específicos para cada posição.

Limitações das container queries

As container queries também não resolvem tudo. Há alguns pontos importantes:

1. Não é possível consultar a altura

No momento, as container queries oferecem suporte apenas à largura. As consultas de altura ainda estão em discussão na especificação.

/* Isto não funciona */
@container (min-height: 400px) {
  /* No momento, ainda não há suporte */
}

2. O contêiner precisa ser um size container

O elemento que recebe @container se torna um “size container”, permitindo que os elementos filhos o consultem. Se você escrever uma container query em um descendente mais profundo, ela consultará o ancestral contêiner mais próximo, que não é necessariamente o pai direto.

3. Não exagere no aninhamento

Muitas camadas de container queries podem afetar o desempenho. Recomendo limitar o aninhamento a duas ou três camadas; além disso, vale considerar uma refatoração.

Estratégia de breakpoints: media queries ou container queries?

Neste ponto, você talvez esteja se perguntando: quando devo usar media queries e quando devo usar container queries?

É uma ótima pergunta.

Minha regra de decisão é simples: observe do que o estilo depende.

Fluxo de decisão

Pergunta: de que este estilo depende?

├─ Depende do tamanho da viewport → Use media queries (md:, lg: etc.)
│   ├─ Layout geral da página
│   ├─ Navegação global, Header e Footer
│   ├─ Seção Hero e anúncios em tela cheia
│   └─ Elementos fixos em determinada posição da viewport
│
└─ Depende do tamanho do contêiner → Use container queries (@sm:, @lg: etc.)
    ├─ Componentes reutilizáveis, como cards e itens de lista
    ├─ Widgets de barra lateral
    ├─ Conteúdo de modais
    └─ Componentes aninhados

Quando usar media queries

Layout da página: use media queries para definir a estrutura de grid da página inteira.

<!-- Layout da página: número de colunas ajustado conforme a viewport -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  <!-- Cards de conteúdo -->
</div>

Esse layout se preocupa com o tamanho da janela do navegador, não com o contêiner.

Navegação global: a expansão ou retração da barra de navegação superior depende da largura da viewport.

<!-- Dispositivo móvel: menu hambúrguer; desktop: navegação horizontal -->
<header class="flex items-center justify-between px-4 py-3">
  <div class="logo">Logo</div>

  <!-- Oculto no celular e visível no desktop -->
  <nav class="hidden md:flex gap-6">
    <a href="/">Início</a>
    <a href="/posts">Artigos</a>
    <a href="/about">Sobre</a>
  </nav>

  <!-- Visível no celular e oculto no desktop -->
  <button class="md:hidden">
    <span class="sr-only">Abrir menu</span>
    <!-- Ícone de menu hambúrguer -->
  </button>
</header>

Quando usar container queries

Componentes reutilizáveis: componentes que serão usados em contêineres com larguras diferentes.

Um card de artigo, por exemplo, pode aparecer em:

• Um fluxo de cards na página inicial, com cerca de 300 a 400px de largura
• Uma seção de artigos relacionados na página do artigo, com cerca de 250px
• Uma lista de artigos recentes na barra lateral, com cerca de 280px

Nesse cenário, as container queries são a melhor opção.

Componentes aninhados: situações em que um componente fica dentro de outro.

<!-- Contêiner externo -->
<div class="@container w-full md:w-80">
  <!-- Contêiner interno -->
  <div class="@container">
    <!-- O elemento mais interno pode ajustar os estilos conforme os dois contêineres -->
    <div class="@sm:flex-row @lg:gap-4">
      ...
    </div>
  </div>
</div>

Como combinar as duas abordagens

Em projetos reais, media queries e container queries costumam ser usadas em conjunto.

Use media queries no nível da página e container queries no nível dos componentes:

<!-- Layout da página: media queries -->
<div class="grid grid-cols-1 md:grid-cols-3 gap-6">

  <!-- Área de conteúdo principal -->
  <main class="md:col-span-2">
    <!-- Componente de card: container query -->
    <div class="@container">
      <article class="flex flex-col @sm:flex-row">
        <!-- Conteúdo do card -->
      </article>
    </div>
  </main>

  <!-- Barra lateral -->
  <aside class="@container">
    <!-- Componente da barra lateral: container query -->
    <div class="@sm:grid-cols-2">
      <!-- Conteúdo do componente -->
    </div>
  </aside>

</div>

A vantagem é que a estrutura geral da página responde ao dispositivo, enquanto o interior de cada componente responde ao espaço realmente disponível. São duas camadas de responsividade, cada uma cumprindo seu papel.

Otimização de desempenho e boas práticas

Para terminar, vejamos alguns pontos importantes no trabalho diário.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

O custo de desempenho das container queries

Sendo sincero, as container queries têm um custo de desempenho. O navegador precisa calcular dimensões adicionais dos contêineres e acompanhar suas mudanças.

Mas esse custo é pequeno, a menos que você exagere no aninhamento.

Certa vez, cometi o erro de adicionar @container a cada item de uma lista e ainda criar várias camadas de contêiner dentro de cada item. O resultado foi uma leve perda de fluidez durante a rolagem da página.

A solução é simples: reduza as camadas de contêiner desnecessárias.

<!-- Não recomendado: @container em todas as camadas -->
<div class="@container">
  <div class="@container">
    <div class="@container">
      <div class="@sm:flex-row">
        <!-- Aninhamento excessivo -->
      </div>
    </div>
  </div>
</div>

<!-- Recomendado: @container apenas onde é necessário -->
<div class="@container">
  <div>
    <div>
      <div class="@sm:flex-row">
        <!-- Somente a camada externa é um contêiner -->
      </div>
    </div>
  </div>
</div>

Não use container queries em excesso

Alguns cenários simplesmente não precisam de container queries.

Uma seção Hero que aparece apenas na página inicial, por exemplo, normalmente tem uma largura bem definida. Nesse caso, media queries são suficientes. Adicionar @container à força só cria complexidade desnecessária.

Minha regra é: use container queries apenas quando o componente precisar ser reutilizado em contêineres com larguras diferentes. Se ele aparecer apenas em um lugar de largura fixa, media queries bastam.

Dicas de depuração

O Chrome DevTools oferece suporte à depuração de container queries, mas o recurso fica um pouco escondido.

Abra o DevTools → painel Elements → selecione um elemento com @container → localize a regra @container no painel Styles → passe o mouse sobre o breakpoint. O Chrome destacará o contêiner correspondente.

Outra opção é procurar por container-type no painel Computed para verificar se o elemento atual é um contêiner de consulta.

Checklist de boas práticas

Para resumir o que aprendi com esses problemas ao longo dos anos:

1. Controle as camadas de contêiner: limite o aninhamento de @container a duas ou três camadas; além disso, considere refatorar
2. Use apenas quando necessário: recorra a container queries somente para componentes reutilizáveis e use media queries em contextos fixos
3. Adote nomes semânticos: nomeie breakpoints por escala de tamanho (sm/md/lg), não por dispositivo (mobile/tablet)
4. Evite seletores complexos: quanto mais simples forem os seletores dentro das container queries, melhor para o desempenho
5. Evite usar em animações: se as dimensões do contêiner mudarem com frequência, não baseie a animação em container queries

Uma última recomendação: teste bastante enquanto escreve o código. Coloque o componente em contêineres de larguras diferentes e confira o resultado; não teste apenas no layout padrão. Muitos problemas só aparecem depois que o projeto entra no ar, quando corrigi-los se torna bem mais trabalhoso.

Conclusão

Chegamos ao fim dos pontos principais. Vamos recapitular.

O problema resolvido pelas container queries é permitir que o componente ajuste o layout ao tamanho real do contêiner, em vez de olhar apenas para a largura da viewport. É isso que possibilita a verdadeira reutilização do componente.

A regra de uso é simples:

• Layout da página → media queries (md:, lg:)
• Componentes reutilizáveis → container queries (@sm:, @lg:)

Quanto ao desempenho, lembre-se de dois pontos: não aninhe demais e não use o recurso em excesso.

Se você tem um componente que precisa funcionar em vários contextos, vale experimentar as container queries. Comece por um card. Depois de adaptá-lo, você perceberá que não precisa mais escrever código repetido para cada lugar em que ele aparece.

Para se aprofundar, consulte a seção Container Queries da documentação oficial do Tailwind ou a página CSS Container Queries da MDN.

Se tiver alguma dúvida, compartilhe nos comentários.