July 14, 2026

Container Query Units: The beauty of cqi and cqb in CSS

Pedro Vieira profile image
Pedro Vieira

Jack of all trades, Master of none

Reading Time: 7 minutes

Go back

If you’ve been working with modern CSS, you’ve probably already come across viewport units such as vw and vh.

They’re incredibly useful. But there’s one fundamental limitation:

Viewport units care about the viewport, not the component.

That becomes a problem when you’re building reusable components.

A card might appear in a large desktop layout, a narrow sidebar, a two-column grid, or inside a completely different component. Its available space can change dramatically, even though the browser viewport hasn’t changed.

This is where container query units come in.

In particular, cqi and cqb allow us to size elements based on the dimensions of their container rather than the browser window.

And once you understand them, they open up some very interesting possibilities for responsive web design.

What are container query units?

Container query units are CSS length units that calculate their size relative to a query container.

They are conceptually similar to viewport units:

  • vw → 1% of the viewport width
  • vh → 1% of the viewport height
  • cqi → 1% of the container’s inline size
  • cqb → 1% of the container’s block size

The important difference is what they’re measuring.

With vw, the browser asks:

“How wide is the viewport?”

With cqi, it asks:

“How wide is the relevant container?”

This makes container units particularly useful for reusable components that can appear in different parts of a layout.

cqi: 1% of the container’s inline size

Let’s start with cqi. cqi stands for Container Query Inline. 1cqi represents 1% of the query container’s inline size.

In a typical left-to-right horizontal layout, the inline axis corresponds to the width.

So, for example, if your container is:

CSS
.container {
    width: 1000px;
}
Then:
CSS
.element {
    width: 50cqi;
}

Would result in approximately: 500px

Because:
1cqi = 1% of 1000px
50cqi = 50% of 1000px

If that same component moves into a container that’s only 600px wide, 50cqi becomes approximately 300px.

The component adapts automatically.

cqb: 1% of the container’s block size

cqb works in a similar way, but it follows the block axis. cqb stands for Container Query Block.

In a typical horizontal writing mode, the block axis runs vertically, so cqb is generally based on the container’s height.

For example:

CSS
.container {
    height: 500px;
}

.element {
    height: 50cqb;
}

The element would be approximately: 250px

Because: 50cqb = 50% of 500px

The important detail here is that cqi and cqb use logical dimensions, rather than simply meaning width and height.

That distinction becomes particularly useful when working with different writing modes and more advanced layouts.

But first: you need a query container

There is an important prerequisite. You can’t simply start using cqi and expect it to automatically understand which element you mean.

You need to establish a container query context.

For example:

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

Now the browser can use that element as a container for container-based sizing.

You can also use the shorthand:

CSS
.card-wrapper {
    container: card / inline-size;
}

Here, card is the container name and inline-size tells the browser which axis should be used for size queries.

Once that’s established, descendants can use container query units.

For example:

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

.card-title {
    font-size: 5cqi;
}

Now the title’s size responds to the container rather than the viewport.

A practical example: responsive typography

One of the most useful applications for cqi is responsive typography.

Imagine you have a card component with a heading:

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

.card h2 {
    font-size: clamp(1.5rem, 5cqi, 4rem);
}

Now the heading can grow as the card gets wider and shrink as the card gets narrower.

The clamp() function is especially useful here because it gives us:

clamp(minimum, preferred, maximum)

So: clamp(1.5rem, 5cqi, 4rem)

Means:

  • Never smaller than 1.5rem
  • Prefer a value based on 5cqi
  • Never larger than 4rem

This gives you fluid sizing without allowing the text to become ridiculously small or large.

Container units are great for spacing too

There’s no reason to restrict cqi to typography.

You can use it for padding, gaps, margins, widths and other properties that accept length values.

For example:

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

.card-content {
    padding: 5cqi;
}

The padding now scales according to the size of the card. A larger card gets more breathing room. A smaller card gets less.

This can be particularly useful when building components that need to maintain consistent proportions across different layouts.

Building a self-contained component

Here’s where container units become particularly interesting.

Imagine you’re creating a reusable product card:

HTML
<article class="product-card">
    <img src="product.jpg" alt="Product">
    <div class="product-card__content">
        <h2>Product Name</h2>
        <p>A short product description.</p>
        <a href="#">View Product</a>
    </div>
</article>

You could make the card a query container:

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

Then make the internal spacing and typography respond to the card itself:

CSS
.product-card__content {
    padding: 4cqi;
}

.product-card h2 {
    font-size: clamp(1.25rem, 4cqi, 2.5rem);
}

.product-card p {
    font-size: clamp(0.875rem, 1.5cqi, 1.125rem);
}

The result is a component that doesn’t need to know whether it’s being displayed:

  • in a full-width section,
  • inside a grid,
  • in a sidebar,
  • inside a modal,
  • or somewhere else entirely.

Its internal sizing adapts to the space available to it.

That’s one of the biggest advantages of container-based responsive design.

One thing to watch out for

Container query units depend on having an appropriate query container.

If there isn’t an eligible container for the relevant axis, the browser falls back to the small viewport unit for that axis.

So if you’re experimenting with cqi or cqb and the result isn’t what you expected, check your container setup first.

For example:

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

is often the missing piece.

Also remember that cqb requires a meaningful block-size context when you want sizing based on the container’s block dimension. In many everyday layouts, cqi is therefore easier to use because width/inline-size is usually the primary responsive dimension.

The bigger idea behind cqi and cqb

The really interesting thing about container query units isn’t the units themselves.

It’s the shift in how we think about responsive design.

Instead of building a page where every component responds to global breakpoints, we can build components that understand their own environment.

That means fewer assumptions. Fewer arbitrary breakpoints. More reusable components. And potentially much more flexible design systems.

cqi and cqb are small additions to CSS syntax, but they represent a much bigger shift:

Responsive design is becoming less about the screen and more about the component.

And that’s a very good thing.

Final thoughts

CSS is moving increasingly toward component-driven responsive design, and container queries are one of the most important pieces of that evolution.

cqi and cqb are especially useful because they allow the actual dimensions of a component’s container to influence its internal sizing.

So next time you’re reaching for vw or adding another media query, ask yourself one question:

Does this element really need to respond to the viewport, or does it actually need to respond to its container?

Sometimes, the answer is cqi. And sometimes, it’s cqb.

Thanks for reading!

If you’ve got a thought, question, or counterpoint, leave a comment below. I’d love to hear from you.Leave a comment
  • CSS
  • Wordpress

Loading..