CSS Container Queries

Container Queries (container queries) are a new CSS feature that allows you to apply styles based on the size of the container, not the size of the browser window. This is a revolutionary change for creating truly modular and reusable components.

What are Container Queries?

Container Queries allow components to adapt to the size of their parent container, not the viewport size. This is especially useful for creating components that can be used in different contexts.

Difference from Media Queries

Media Queries respond to browser window size:

@media (min-width: 768px) {
  .card {
    width: 50%;
  }
}

Container Queries respond to container size:

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

@container (min-width: 400px) {
  .card {
    width: 50%;
  }
}

How to Use Container Queries

Declaring a Container

First, you need to declare an element as a container:

.card-container {
  container-type: inline-size;
  /* or */
  container-type: size;
  /* or */
  container-type: normal; /* default, does not create container */
}

Container types:

inline-size — tracks only width (inline dimension)
size — tracks both width and height
normal — does not create a container

Using @container

After declaring a container, you can use queries:

.card {
  padding: 1rem;
  font-size: 1rem;
}

@container (min-width: 400px) {
  .card {
    padding: 2rem;
    font-size: 1.25rem;
  }
}

@container (min-width: 600px) {
  .card {
    padding: 3rem;
    font-size: 1.5rem;
  }
}

Practical Example

<div class="sidebar">
  <div class="card-container">
    <div class="card">
      <h3>Card Title</h3>
      <p>Card text adapts to container size.</p>
    </div>
  </div>
</div>

<div class="main-content">
  <div class="card-container">
    <div class="card">
      <h3>Card Title</h3>
      <p>Same card, but in a different context.</p>
    </div>
  </div>
</div>

.sidebar {
  width: 300px;
}

.main-content {
  width: 800px;
}

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

.card {
  background: #f0f0f0;
  padding: 1rem;
  border-radius: 8px;
}

/* Card adapts to container size */
@container (min-width: 400px) {
  .card {
    display: flex;
    gap: 1rem;
  }
  
  .card h3 {
    font-size: 1.5rem;
  }
}

@container (min-width: 600px) {
  .card {
    padding: 2rem;
  }
  
  .card h3 {
    font-size: 2rem;
  }
}

Named Containers

You can give a container a name for more precise control:

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

.main-content {
  container-type: inline-size;
  container-name: main;
}

/* Styles apply only to container named "sidebar" */
@container sidebar (min-width: 300px) {
  .card {
    /* styles for card in sidebar */
  }
}

/* Styles apply only to container named "main" */
@container main (min-width: 600px) {
  .card {
    /* styles for card in main */
  }
}

Container Query Units

Container Queries introduce new units of measurement:

cqw — 1% of container width
cqh — 1% of container height
cqi — 1% of container inline-size
cqb — 1% of container block-size
cqmin — smaller value of cqi and cqb
cqmax — larger value of cqi and cqb

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

.card {
  font-size: clamp(1rem, 4cqw, 2rem);
  padding: clamp(1rem, 5cqw, 3rem);
}

Combining with Media Queries

Container Queries and Media Queries can be used together:

/* Media Query for general layout */
@media (min-width: 1024px) {
  .page {
    display: grid;
    grid-template-columns: 1fr 3fr;
  }
}

/* Container Query for component */
.card-container {
  container-type: inline-size;
}

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

Browser Support

Container Queries are supported in modern browsers:

Chrome 105+
Firefox 110+
Safari 16.0+
Edge 105+

For older browsers, you can use a polyfill or fallback via Media Queries.

Advantages of Container Queries

Modularity: Components become truly independent
Reusability: One component works in different contexts
Flexibility: Easier to create responsive designs
Better performance: Browser can optimize rendering

When to Use

Use Container Queries when:

Component should adapt to container size, not viewport
Creating reusable components
Need more flexible responsiveness

Use Media Queries when:

Need to change overall page layout
Adaptation depends on device screen size
Working with old browsers

Tip:

Container Queries are a powerful tool for creating modular components. Use them together with Media Queries to create flexible and responsive interfaces.

Back

Forward

Content

What are Container Queries?Difference from Media Queries How to Use Container Queries Declaring a Container Using @container Practical Example Named Containers Container Query Units Combining with Media Queries Browser Support Advantages of Container Queries When to Use