CSS Container Queries
A container query changes a component's style based on the size of its parent box, not the size of the whole screen.
The Problem with Media Queries
A media query looks at the screen width. But a card may sit in a wide main column on one page and in a narrow sidebar on another, on the same laptop screen. The screen size is the same, yet the card has very different space.
Container queries fix this. The card asks: "How wide is my container?" and styles itself to fit.
| Media query | Container query | |
|---|---|---|
| Looks at | The viewport (screen) | A parent element |
| Written as | @media (min-width: 600px) | @container (min-width: 400px) |
| Best for | Page layout | Reusable components |
Step 1: Make a Container
Tell the browser which element is the container with container-type.
Example
.card-wrap {
container-type: inline-size;
}inline-size means "watch the width". (In English text, the inline direction is left to right.) There is also size, which watches width and height, but it needs a fixed height, so inline-size is what you will use almost every time.
Step 2: Write the @container Rule
Inside @container, style the children of the container.
Example
@container (min-width: 400px) {
.card {
display: flex;
gap: 16px;
}
}A container cannot style itself in its own query, only the elements inside it. That is why you usually add a wrapper element around the component.
A Full Example
The same card is used twice: once in a wide area and once in a narrow sidebar. Nothing else changes, yet they look different.
Example
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
body { font-family: Arial, sans-serif; margin: 16px; }
.layout {
display: grid;
grid-template-columns: 2fr 1fr;
gap: 16px;
}
.card-wrap {
container-type: inline-size;
}
.card {
border: 1px solid #cbd5e1;
border-radius: 8px;
padding: 12px;
}
.card .thumb {
background-color: #264de4;
color: white;
aspect-ratio: 16 / 9;
display: grid;
place-items: center;
border-radius: 6px;
}
.card h3 { margin: 10px 0 4px; }
@container (min-width: 380px) {
.card {
display: flex;
gap: 16px;
align-items: center;
}
.card .thumb { width: 160px; flex-shrink: 0; }
.card h3 { margin-top: 0; }
}
</style>
</head>
<body>
<div class="layout">
<div class="card-wrap">
<div class="card">
<div class="thumb">Photo</div>
<div>
<h3>Graphic Design Course</h3>
<p>Photoshop, Illustrator and Canva in 2 months.</p>
</div>
</div>
</div>
<div class="card-wrap">
<div class="card">
<div class="thumb">Photo</div>
<div>
<h3>Graphic Design Course</h3>
<p>Photoshop, Illustrator and Canva in 2 months.</p>
</div>
</div>
</div>
</div>
</body>
</html>In the wide column the card shows the photo beside the text. In the narrow column the photo sits on top. Make the result window narrower, and the wide card also switches when its column gets below 380px.
Named Containers
When containers are inside other containers, a query looks at the nearest one. Give a container a name to pick a specific one.
Example
.sidebar {
container-type: inline-size;
container-name: sidebar;
}
/* Shorthand: name / type */
.main {
container: main / inline-size;
}
@container sidebar (max-width: 250px) {
.menu a { font-size: 0.875rem; }
}Container Query Units
Inside a container, you can size things relative to the container itself:
| Unit | Equals |
|---|---|
cqw | 1% of the container's width |
cqh | 1% of the container's height |
cqi | 1% of the container's inline size (usually width) |
cqmin / cqmax | The smaller or larger of cqi and cqb |
Example
.card h3 {
font-size: clamp(1rem, 5cqi, 1.75rem);
}The heading now grows with the card, not with the screen.
When to Use Which
- Use media queries for the big page layout: how many columns, when to show the mobile menu
- Use container queries for components that are reused in different places: cards, widgets, product boxes
Container queries work in all modern browsers since 2023, so you can use them in real projects today.
Exercise
Exercise
What must you add to a parent element before @container rules can respond to its width?