CSS Container Queries

The Problem with Media Queries for Components

Media queries look at the viewport. But a component doesn't care about the viewport — it cares about the space it's given:

/* ❌ Media query — doesn't work when the card is in a sidebar */
.card { display: flex; flex-direction: column; }

@media (min-width: 1024px) {
    .card { flex-direction: row; }
}

/* Problem: On a 1920px desktop, the card is in a 300px sidebar.
   The viewport is wide, so the card goes horizontal.
   But the card only has 300px — it looks broken. */

Container queries fix this. The card responds to its parent's width, not the viewport.

The Basic Syntax

/* 1. Define the container */
.card-wrapper {
    container-type: inline-size;
    container-name: card;
}

/* 2. Style descendants based on container size */
@container card (min-width: 400px) {
    .card {
        flex-direction: row;
    }
}

Two properties set up the container:

• container-type: inline-size — the container can be queried by its inline (horizontal) size.
• container-name: card — an optional name. If omitted, the nearest ancestor container is used.

Container Query Units

Container queries come with their own units, relative to the container — not the viewport:

@container card (min-width: 400px) {
    .card-title {
        font-size: clamp(1rem, 0.5rem + 3cqi, 2rem);
    }
}

The three units:

• cqi — 1% of the container's inline size (usually width).
• cqw — 1% of the container's width.
• cqb — 1% of the container's block size (usually height).

Combined with clamp(), these create fluid typography that scales with the component, not the screen.

Container Queries + clamp() = Fluid Components

This combination is the modern way to build self-contained, responsive components:

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

.card-title {
    font-size: clamp(1rem, 0.5rem + 3cqi, 2rem);
}

.card-body {
    padding: clamp(1rem, 5cqi, 2rem);
}

The title and padding scale with the card's container. Move the card from a full-width page to a narrow sidebar, and everything adjusts automatically.

Media Queries vs Container Queries — When to Use Each

Use media queries for macro layout (page structure). Use container queries for micro layout (components).