css - CSS Container Queries

CSS Container Queries are a modern CSS feature that allows styles to change based on the size or state of a parent container rather than the size of the entire browser viewport. This gives developers much more control when building reusable and responsive components.

Before container queries, responsive design mainly depended on media queries. Media queries check the width or height of the browser window. While this works well for full-page layouts, it becomes difficult when components are reused in different sections of a website. A card component placed inside a narrow sidebar may need different styling than the same card placed in a wide content area. Media queries cannot easily solve this problem because they only look at the viewport size.

Container queries solve this issue by allowing elements to respond to the dimensions of their own parent container.

Why Container Queries Are Important

Modern web applications use reusable components such as:

  • Product cards

  • Navigation menus

  • Dashboards

  • Widgets

  • Sidebars

  • Profile sections

These components may appear in different layouts and different widths. Container queries make components truly independent and flexible.

Advantages include:

  • Better component reusability

  • More modular design systems

  • Cleaner responsive layouts

  • Reduced dependency on viewport-based breakpoints

  • Easier maintenance in large projects

Basic Concept

A container query works in two steps:

  1. Define a container

  2. Apply styles based on the container’s size

The child elements inside the container can then react to the container dimensions.

Step 1: Defining a Container

To use container queries, a parent element must first be declared as a container.

Example:

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

Understanding container-type

The container-type property tells the browser which type of container should be monitored.

Common values:

Value Description
inline-size Tracks width changes only
size Tracks both width and height
normal Default value, no container query support

Most developers use inline-size because width-based responsiveness is more common.

Step 2: Writing a Container Query

Once the container is defined, styles can change according to container width.

Example:

@container (min-width: 500px) {
    .card {
        display: flex;
    }
}

This means:

  • If the container becomes at least 500px wide

  • The .card element changes to flex layout

Unlike media queries, this does not depend on screen size.

Complete Example

HTML

<div class="card-wrapper">
    <div class="card">
        <img src="image.jpg" alt="Sample">
        <div class="content">
            <h2>Product Title</h2>
            <p>Product description goes here.</p>
        </div>
    </div>
</div>

CSS

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

.card {
    padding: 20px;
    border: 1px solid #ccc;
}

@container (min-width: 600px) {
    .card {
        display: flex;
        gap: 20px;
    }

    .card img {
        width: 200px;
    }
}

How It Works

  • When the container width is below 600px:

    • The card appears vertically stacked

  • When the container width reaches 600px:

    • The layout becomes horizontal using flexbox

This behavior happens regardless of screen size.

Naming Containers

Containers can also be given names for better organization.

Example:

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

Then use:

@container dashboard-container (min-width: 700px) {
    .widget {
        grid-template-columns: 1fr 1fr;
    }
}

This is useful when multiple containers exist on the page.

Container Query Units

CSS also introduces special container-relative units.

Common Units

Unit Description
cqw 1% of container width
cqh 1% of container height
cqi 1% of inline size
cqb 1% of block size
cqmin Smaller of width or height
cqmax Larger of width or height

Example:

.title {
    font-size: 5cqw;
}

The font size changes according to container width.

Comparison Between Media Queries and Container Queries

Feature Media Queries Container Queries
Based On Viewport size Parent container size
Reusable Components Limited Excellent
Responsive Cards Difficult Easy
Component Independence Low High
Best For Full-page layouts Component layouts

Nested Responsive Components

Container queries are especially powerful in nested layouts.

Example:

  • A card inside a sidebar

  • A card inside a main section

Even on the same page:

  • Sidebar card can stay vertical

  • Main content card can become horizontal

This was difficult using only media queries.

Real-World Use Cases

Dashboard Widgets

Widgets resize automatically depending on dashboard column width.

E-Commerce Product Cards

Cards adjust layouts inside different product grids.

Responsive Navigation

Menus adapt based on available container space.

Blog Layouts

Article cards respond differently in sidebars versus featured sections.

Design Systems

Reusable UI libraries become easier to maintain.

Combining Container Queries with Grid

Example:

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

@container (min-width: 800px) {
    .gallery-items {
        display: grid;
        grid-template-columns: repeat(4, 1fr);
    }
}

This creates layouts based on component width instead of viewport width.

Browser Support

Container queries are supported in most modern browsers including:

  • Google Chrome

  • Microsoft Edge

  • Firefox

  • Safari

Older browsers may require fallback designs.

Best Practices

Use Component-Based Design

Container queries work best with modular UI components.

Prefer inline-size

Width-based responsiveness is usually enough.

Avoid Overusing Queries

Too many nested queries may increase complexity.

Combine with Media Queries

Use media queries for overall page layout and container queries for internal components.

Example Combining Both

@media (max-width: 768px) {
    body {
        padding: 10px;
    }
}

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

@container (min-width: 500px) {
    .card {
        display: flex;
    }
}

Here:

  • Media query controls page layout

  • Container query controls component behavior

Limitations

Initial Learning Curve

Developers familiar only with media queries may need practice.

Browser Compatibility

Very old browsers may not support container queries.

Performance Considerations

Large numbers of complex container queries can affect rendering performance.

Future of Responsive Design

Container queries are considered one of the most important improvements in modern CSS because they support true component-driven development. As frameworks and design systems continue evolving, container queries will likely become a standard practice in responsive web design.

They shift responsive design from page-based thinking to component-based thinking, which aligns perfectly with modern frontend development approaches.