📦 Container Query Units — cqw, cqh, cqi, cqb, cqmin, cqmax

🌐 What Are Container Query Units?

Container Query Units allow elements to size themselves based on thedimensions of their nearest container — not the viewport. These units are essential for component-level responsive design.

>>“Container query units let components be responsive inside any layout — no media queries needed.”

Note

✔ Works only inside elements that are set as container-type: size, inline-size, or normal
✔ Perfect for responsive cards, grids, navbars, widgets

📦 Overview of Container Units

UnitMeaningRelative To
cqwContainer Query Width1% of container width
cqhContainer Query Height1% of container height
cqiContainer Inline Size1% of container inline dimension
cqbContainer Block Size1% of container block dimension
cqminSmaller of inline/block sizemin(cqi, cqb)
cqmaxLarger of inline/block sizemax(cqi, cqb)

Note

✔ cqi/cqb work even in different writing modes
✔ cqmin/cqmax behave like vmin/vmax but for containers

📌 Make a Container First

Enable Container Queries

.card {
  container-type: inline-size; /* or size */
}

Once a container is enabled, child elements can use container query units.

🔢 1. cqw — Container Width

cqw Example

.title {
  font-size: 5cqw; /* scales with container width */
}

Perfect for responsive card titles that grow/shrink with their card container.

📏 2. cqh — Container Height

cqh Example

.box {
  height: 50cqh; /* 50% of container height */
}

Note

Useful for widgets, sidebars, or flexible dashboard tiles.

🔤 3. cqi & cqb — Writing-Mode Aware Units

cqi = inline direction
cqb = block direction
These change depending on writing-mode.

cqi/cqb Example

.paragraph {
  padding-inline: 4cqi;
  padding-block: 2cqb;
}

Important for internationalization (vertical writing modes, RTL languages).

🔺 4. cqmin & cqmax

Similar to vmin/vmax, but based on container size.

cqmin/cqmax Example

.avatar {
  width: 20cqmin;
  height: 20cqmin; /* perfect responsive square */
}

🧠 How Container Units Compare

UnitContainer-Based?Writing-Mode Aware?
cqw✔ Yes❌ No
cqh✔ Yes❌ No
cqi✔ Yes✔ Yes
cqb✔ Yes✔ Yes
cqmin✔ Yes✔ Yes
cqmax✔ Yes✔ Yes

🧪 Practical Examples

1️⃣ Responsive Card Layout

Responsive Card

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

.card-title {
  font-size: 4cqw;
}

.card-content {
  padding: 3cqi; /* inline-aware padding */
}

2️⃣ Adaptive Avatar Scaling

Avatar example

.profile {
  container-type: size;
}

.avatar {
  width: 30cqmin;
  height: 30cqmin;
  border-radius: 50%;
}

Avatar stays perfectly proportional regardless of container shape.

3️⃣ Dashboard Tile Resizing

Dashboard widget

.tile {
  container-type: size;
}

.tile-content {
  font-size: 2cqmax; /* grows with largest container dimension */
}

📚 Real Use Cases

  • Responsive cards that scale depending on grid column width
  • Dashboard components that resize inside tiles
  • Reusable UI components that adapt in any parent container
  • Fully fluid typographic systems inside components
  • Widgets with proportional aspect ratios

⚠️ Common Mistakes & Gotchas

  • ❌ Forgetting to set container-type
  • ❌ Expecting container units to work without a container
  • ❌ Using cqh when the container height is auto → unstable results
  • ❌ Mixing container units with vh/vw inconsistently

Note

🎯 BEST PRACTICE → Use inline-size container type for most UI components.

🔥 Summary

Container units (cqw, cqh, cqi, cqb, cqmin, cqmax) makecomponent-level responsive design possible without relying on global media queries. They adapt UI elements based on the size of their nearest container — making components portable, flexible, and truly reusable.

>>“Design components that respond to their container, not the entire page.”

Learn more →MDN Docs 📘