CSS Container Queries vs Media Queries: When to Use Which

For over a decade, responsive web design relied almost exclusively on CSS Media Queries (@media). While media queries enabled websites to adapt to varying device screens, they suffer from a fundamental architectural limitation: they inspect the viewport, not the parent container. CSS Container Queries (@container) solve this problem permanently, ushering in the true era of modular component-driven styling.

The Viewport Limitation Problem

Consider a standard reusable UI component: a product or profile card. In modern web apps, that same card might appear in:

• A full-width hero section (spanning 1200px)
• A 3-column grid (spanning ~380px each)
• A narrow sidebar widget (spanning 280px)

With traditional @media queries, the card only knows the width of the entire browser window. If the user is on a desktop monitor (1920px wide), the media query assumes there is ample room and renders a wide horizontal layout—even if the card is crammed into a 250px sidebar, causing broken layouts and awkward text truncation.

Enter CSS Container Queries

Container queries allow an element to inspect the styling and dimensions of its direct parent container rather than the overall browser viewport. A component can now adapt dynamically based on the space allocated to it, regardless of where it is placed in the DOM tree.

Step 1: Establishing a Containment Context

To use container queries, you first declare a parent element as a containment context using the container-type property:

/* Define the parent element as a responsive container */
.card-wrapper {
    container-type: inline-size;
    container-name: cardContainer;
}

The inline-size value instructs the browser to monitor changes to the horizontal width of the container. Specifying a container-name is optional but recommended when nesting multiple containers.

Step 2: Writing Container Queries

Once containment is defined, child elements can use the @container rule to adapt based on the container's width:

/* Default style: Mobile / Narrow layout (under 400px container width) */
.user-card {
    display: flex;
    flex-direction: column;
    padding: 1rem;
    background: #1a1a2e;
    border-radius: 12px;
}

.user-card img {
    width: 100%;
    height: 180px;
    object-fit: cover;
    border-radius: 8px;
}

/* Wide Container: When container has 450px or more space */
@container cardContainer (min-width: 450px) {
    .user-card {
        flex-direction: row;
        align-items: center;
        gap: 1.5rem;
        padding: 1.5rem;
    }

    .user-card img {
        width: 140px;
        height: 140px;
        flex-shrink: 0;
    }
}

/* Extra Wide Container: When container exceeds 700px */
@container cardContainer (min-width: 700px) {
    .user-card {
        padding: 2rem;
        background: linear-gradient(135deg, #1a1a2e, #16213e);
    }

    .user-card .card-bio {
        font-size: 1.1rem;
        line-height: 1.6;
    }
}

Container Query Length Units

Just as viewport units (vw, vh) exist for browser dimensions, container queries introduce dedicated units relative to the container:

• cqw: 1% of the query container's width.
• cqh: 1% of the query container's height.
• cqi: 1% of the query container's inline size.
• cqb: 1% of the query container's block size.
• cqmin / cqmax: The smaller or larger value of cqi or cqb.

These units allow fluid typography that scales perfectly within modular widgets without overflowing:

.widget-heading {
    font-size: clamp(1rem, 4cqi, 2.5rem);
}

Comparison: Media Queries vs. Container Queries

Summary: How to Use Both in Harmony

Container queries do not replace media queries; they complement them. The modern standard is: use Media Queries for macro-layouts (defining page grids, drawer menus, and overall page margins) and use Container Queries for micro-layouts (components, cards, form controls, and nested widgets). This hybrid pattern delivers bulletproof responsiveness across all screen sizes and placement contexts.