CSS container queries and responsive layouts — Crash Course — Practical Guide (Nov 6, 2025)

CSS container queries and responsive layouts — Crash Course

Level: Intermediate

Published: 6 November 2025

Introduction

Responsive design is foundational in modern web development. Traditionally, media queries have empowered developers to tailor styles based on viewport dimensions. However, they come with limitations — especially when components need to respond to their container size rather than the entire viewport.

Enter CSS container queries, a relatively new CSS feature that allows styling elements based on the size of their parent container. This approach complements media queries and enables truly modular, reusable components.

This crash course will guide you through practical usage of container queries, their integration into responsive layouts, and the common pitfalls to watch out for. We will also compare container queries with media queries to understand when to use each.

Prerequisites

This article assumes you have intermediate knowledge of CSS and responsive design principles, including familiarity with media queries and Flexbox or Grid layouts.

Browser support and versions:

Chrome: Full support since version 105+
Firefox: Supported since version 109+
Safari: Supported since version 16.4+
Edge: Support aligns with Chromium, version 105+
Note: Internet Explorer and legacy browsers do not support container queries.

If you require support on older browsers, graceful degradation or fallback styles using media queries are necessary.

Understanding CSS Container Queries

Container queries enable styling of an element based on the inline-size (width), block-size (height), or other dimension of its container rather than the viewport. This is powerful for components embedded in various layouts or when containers can change size independent of screen dimensions.

At their core, two main parts are involved:

container-type: Declares an element as a container to be queried against.
@container rule: CSS conditional block applying styles based on container size or characteristics.

Defining a container

To enable container queries, you must define your container element using container-type. The common value is inline-size, which monitors width changes.

.card-container {
  container-type: inline-size;
  /* Optional: container-name: card-box; */
}

This registers the element as a container whose inline size will be used for queries inside it.

Writing a container query

A container query looks similar to a media query but targets the container’s properties.

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

This applies when the container’s inline size is at least 400px. You can use max-width, and other length-based queries as well.

Hands-on Steps: Building a Responsive Card

Let’s create a responsive card component which changes layout based on container width.

Step 1: Set up the HTML structure

<div class="card-container">
  <article class="card">
    <img src="thumbnail.jpg" alt="Thumbnail" class="card-img" />
    <div class="card-content">
      <h2 class="card-title">Card Title</h2>
      <p class="card-text">Lorem ipsum dolor sit amet...</p>
    </div>
  </article>
</div>

Step 2: Define the container and basic styles

.card-container {
  container-type: inline-size;
  width: 100%;
  max-width: 600px;
  margin: 0 auto;
  border: 1px solid #ddd;
  padding: 12px;
}

.card {
  border-radius: 6px;
  padding: 16px;
  background: #fff;
  box-shadow: 0 2px 8px rgb(0 0 0 / 0.1);
}

.card-img {
  width: 100%;
  height: auto;
  border-radius: 6px;
}

Step 3: Apply container query to change layout

@container (min-width: 400px) {
  .card {
    display: flex;
    gap: 16px;
  }
  .card-img {
    flex: 0 0 150px;
    width: auto;
  }
  .card-content {
    flex: 1 1 auto;
  }
}

When the container exceeds 400px, the card switches to a horizontal flex layout, placing the image alongside content. Below 400px, it defaults to stacked vertical block layout.

When to Choose Container Queries over Media Queries

Use container queries when:

Components need to adapt to their container dimensions, e.g. embedded widgets or cards inside resizable containers.
You want truly modular components that respond consistently irrespective of viewport size.
Supporting complex nested responsive behaviours where viewport-based breakpoints are insufficient.

Use media queries for:

Global layout adjustments based on screen/viewport size.
When supporting legacy browsers that do not support container queries.
Simpler and well-established responsive patterns based on breakpoints.

Common Pitfalls

Forgetting to set container-type: Container queries only work inside elements declared as containers.
Unexpected inheritance and specificity: Container query styles cascade normally; be mindful of specificity to avoid conflicts.
Performance considerations: Container queries add complexity to layout recalculations. Keep queries simple and avoid deep nesting.
Limited support in email clients and old browsers: Always test and provide fallbacks where necessary.
Units and dimension types: Container queries primarily check inline-size and block-size; be precise with units (px, em, etc.).

Validating Container Queries

To verify your container queries are working:

Use browser developer tools: Inspect the container element and observe the CSS rules applied when resizing the container.
Resize the container dynamically if possible, e.g., by adding a range input slider controlling container width in a demo page.
Check browser support and any warnings in devtools consoles about unsupported properties.
Run automated style audit tools that support CSS features validation. Some linters might flag unsupported syntax if your config is outdated.

Checklist / TL;DR

Declare parent containers with container-type: inline-size; or size; (experimental).
Write container queries with @container (min-width: X) instead of @media.
Use container queries for component-level responsiveness; media queries for global viewport control.
Test across browsers supporting container queries (Chrome 105+, Firefox 109+, Safari 16.4+).
Watch performance by avoiding complex, deeply nested container-query-heavy UIs.
Provide fallback styles if legacy browser support is needed.