Skip to main content

Unidades cqw e cqi no CSS | CSS

  • Unidades cqw e cqi no CSS | CSS

Definição​

As unidades cqw e cqi fazem parte das Container Query Units, permitindo que elementos sejam dimensionados com base no tamanho do container pai, ao invés da viewport.

Isso resolve limitações clássicas de responsividade onde componentes dependem da tela inteira (vw, vh) ao invés do contexto onde estão inseridos.

Conceitos fundamentais​

cqw​

  • Representa 1% da largura do container
  • Baseado no eixo físico horizontal
.box {
  width: 50cqw;
}

Se o container tiver 400px, o resultado será:

50cqw = 200px

cqi​

  • Representa 1% do inline-size do container
  • Baseado no eixo inline (depende do modo de escrita)
.title {
  font-size: 5cqi;
}

Em layout padrão (horizontal LTR):

5cqi = 5% da largura do container

Em layout vertical, o eixo inline muda → comportamento diferente

Pré-requisito obrigatório​

Para usar cqw e cqi, o container precisa declarar:

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

Sem isso, o comportamento pode cair para valores baseados na viewport.

Comparação com outras unidades​

cqw vs %​

.box {
  width: 50%;
}
  • % depende do contexto do layout
  • pode ser afetado por padding, display, box-sizing
.box {
  width: 50cqw;
}
  • sempre relativo ao container definido
  • comportamento mais previsível em componentes

cqw vs vw​

.box {
  width: 50vw;
}
  • relativo à viewport (tela inteira)
.box {
  width: 50cqw;
}
  • relativo ao container

Diferença prática:

  • vw → layout global
  • cqw → layout local (componente)

cqi vs cqw​

  • cqw → largura física
  • cqi → eixo inline (semântico)

Use cqi quando quiser compatibilidade com:

  • idiomas RTL
  • layouts verticais

Exemplo completo​

<div class="wrapper">
  <div class="card">
    <h1 class="title">Título</h1>
    <div class="box"></div>
  </div>
</div>
.wrapper {
  width: 800px;
}

.card {
  width: 400px;
  container-type: inline-size;
  border: 1px solid #000;
}

.title {
  font-size: 4cqi;
}

.box {
  width: 50cqw;
  height: 50px;
  background: gray;
}

Resultado:

  • .title → 4% do container (16px)
  • .box → 200px

Uso com @container​

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

.title {
  font-size: 2cqi;
}

@container (min-width: 300px) {
  .title {
    font-size: 4cqi;
  }
}

Aqui o comportamento é baseado no tamanho do container, não da tela.

Casos de uso​

Componentes reutilizáveis​

  • cards
  • widgets
  • tabelas
  • dashboards

Permite que o componente se adapte ao espaço onde está inserido

Tipografia responsiva local​

.title {
  font-size: clamp(14px, 3cqi, 28px);
}

Escala com o container, não com a tela

Layouts independentes​

  • grids dentro de sidebars
  • modais
  • componentes embedados

Boas práticas​

  • use container-type: inline-size sempre que possível
  • prefira cqi para tipografia
  • use cqw para largura de elementos
  • combine com clamp() para controle de limites
  • evite misturar vw com cqw no mesmo contexto sem necessidade

Limitações​

  • suporte ainda em evolução em alguns browsers antigos
  • exige definição explícita do container
  • pode gerar confusão com % se usado incorretamente

Regra prática​

  • layout global → vw
  • layout de componente → cqw
  • tipografia adaptativa → cqi
  • casos simples → %