CSS Container Queries
Media queries let components respond to the viewport width. Container queries let them respond to the width of their parent container. This seemingly small shift unlocks truly reusable, placement-agnostic components — the same card component can display in a compact vertical layout when placed in a narrow sidebar and switch to a horizontal layout when placed in a wide main column, all at the same viewport width, with no JavaScript and no additional class names.
Media Queries vs Container Queries
The fundamental difference: media queries watch the viewport, container queries watch the element's parent. This matters enormously for reusable components:
in a wide layout, vertical when narrow.
@media (min-width: 768px) {
.card { flex-direction: row }
}
✗ Card in a 200px sidebar becomes
horizontal at 768px viewport even
though there's no room for it.
The component doesn't know
where it is placed.
its own available space.
@container (min-width: 320px) {
.card { flex-direction: row }
}
✓ Card in sidebar stays vertical.
Card in wide main column goes
horizontal. Same component.
The component adapts to
where it is placed.
↑ Zero JavaScript. Same CSS class. Different parent container width.
Container Query Syntax
Two steps: mark the parent as a query container, then
write @container rules that
style the children based on that container's size:
on the PARENT element
enables width-based queries
the query rule
same syntax as @media
/* ── Step 1: mark the PARENT as a container ── */
.card-wrapper {
container-type: inline-size; /* enable width-based queries */
}
/* container-type values:
inline-size → query on inline (width) dimension ← most common
size → query on both width AND height
style → style queries (CSS variable-based)
normal → no containment (default) */
/* ── Step 2: write @container rules for CHILDREN ── */
@container (min-width: 400px) {
.card { flex-direction: row; }
}
/* ── Shorthand: container property ── */
.card-wrapper {
container: inline-size; /* shorthand for container-type */
/* or */
container: card / inline-size; /* name / type */
}
/* ── Multiple breakpoints ── */
@container (min-width: 200px) {
.card { padding: 12px; }
}
@container (min-width: 400px) {
.card { flex-direction: row; }
}
@container (min-width: 600px) {
.card { grid-template-columns: 1fr 2fr; }
}
/* ── Range syntax (CSS Level 5) ── */
@container (200px <= width <= 600px) {
.card { background: pink; }
}
/* ── max-width queries ── */
@container (max-width: 300px) {
.card-actions { display: none; } /* hide on narrow */
}
Named Containers
When you have nested containers or want a component to query a
specific ancestor rather than the nearest one, use
container-name. The
@container rule then targets
that named container by name:
/* ── Naming containers ── */
.sidebar {
container-type: inline-size;
container-name: sidebar;
/* shorthand: container: sidebar / inline-size; */
}
.main-content {
container-type: inline-size;
container-name: main-content;
}
/* ── Query a SPECIFIC named container by name ── */
@container sidebar (min-width: 200px) {
.widget { flex-direction: column; }
}
@container main-content (min-width: 400px) {
.widget { grid-template-columns: 1fr 2fr; }
}
/* ── Multiple names on one container ── */
.el { container-name: layout article; } /* space-separated list */
/* ── Without a name: @container queries the NEAREST container ── */
@container (min-width: 300px) {
.child { color: blue; } /* applies when nearest container ≥ 300px */
}
Container Query Units
Container query units are like viewport units (vw, vh) but relative to the
nearest container instead of the viewport. They let values scale
with the container rather than the viewport:
Resize the browser — these bars track the column width, not the viewport
/* Container query units — relative to nearest container */
/* cqi = 1% of container inline-size (width in horizontal writing)
cqb = 1% of container block-size (height in horizontal writing)
cqw = 1% of container width (explicit)
cqh = 1% of container height (explicit)
cqmin= 1% of smaller dimension
cqmax= 1% of larger dimension */
/* ── Usage ── */
.wrapper { container-type: inline-size; }
.child {
font-size: 4cqi; /* 4% of container width — fluid text */
padding: 3cqi 5cqi; /* fluid padding */
width: 80cqi; /* 80% of container width */
}
/* ── Like clamp() but container-relative ── */
.card-title {
font-size: clamp(0.875rem, 3cqi, 1.5rem);
/* grows with container, bounded by rem extremes */
}
/* ── Why cqi over vw ── */
/* vw is always viewport width — sidebar content uses vw of full page
cqi is container width — sidebar content uses sidebar width ← correct */
.sidebar { container-type: inline-size; }
.sidebar p { font-size: 4cqi; } /* scales with sidebar width — not viewport */
/* ── Combined with @container ── */
.card-wrapper { container-type: inline-size; }
.card-img { width: min(30cqi, 120px); } /* fluid but capped */
@container (min-width: 350px) {
.card-title { font-size: max(1rem, 3cqi); }
}
Real-World Patterns
- Card components (sidebar vs main column)
- Media objects (image + text)
- Nav menus (hamburger vs full)
- Data tables (cards vs rows)
- Design system components
- Overall page layout breakpoints
- Viewport-level navigation changes
- Font size on body/root
- Print styles
- prefers-color-scheme, motion
/* ── 1. Card component (sidebar/main column aware) ── */
.card-container { container-type: inline-size; }
.card {
display: flex;
flex-direction: column; /* default: vertical (narrow) */
}
@container (min-width: 320px) {
.card { flex-direction: row; } /* horizontal when room */
.card-image { width: min(30cqi, 140px); }
}
/* ── 2. Product grid — auto-switch between grid and list ── */
.product-grid { container-type: inline-size; }
.product-list {
display: grid;
grid-template-columns: 1fr; /* single column, narrow */
}
@container (min-width: 480px) {
.product-list { grid-template-columns: repeat(2, 1fr); }
}
@container (min-width: 720px) {
.product-list { grid-template-columns: repeat(3, 1fr); }
}
/* ── 3. Navigation — compact in sidebar, full elsewhere ── */
.nav-wrapper { container: nav / inline-size; }
.nav-menu { display: none; } /* hidden narrow */
.hamburger { display: flex; }
@container nav (min-width: 500px) {
.nav-menu { display: flex; }
.hamburger{ display: none; }
}
/* ── 4. Data table → cards on narrow ── */
.table-wrap { container-type: inline-size; }
table { display: none; } /* hidden until wide */
.card-list { display: block; } /* show cards narrow */
@container (min-width: 600px) {
table { display: table; }
.card-list { display: none; }
}
/* ── 5. Fluid typography with cqi ── */
.article { container-type: inline-size; }
.article h2{ font-size: clamp(1.25rem, 4cqi, 2.5rem); }
.article p { font-size: clamp(0.875rem, 2cqi, 1.125rem); }
Container Query Reference
| Property / Unit | Value / Syntax | What it does |
|---|---|---|
| container-type | inline-size, size, normal | Establishes query container and which dimensions can be queried |
| container-name | any name (or none) | Names the container so @container can target it specifically |
| container | name / type | Shorthand for container-name and container-type |
| @container | @container [name] (condition) | Applies styles when the container matches the condition |
| cqi | 1% of container inline size | Like vw but for the container — scales with container width |
| cqb | 1% of container block size | Like vh but for the container — scales with container height |
| cqw / cqh | 1% of container width/height | Explicit width/height versions of cqi/cqb |
| cqmin / cqmax | 1% of smaller/larger dimension | Like vmin/vmax but for the container |
Try It Yourself
A resizable container demo — drag the preview pane divider to see the card component adapt based on container width, not viewport:
Quick Check — Chapter 51
@media (min-width: 768px) { .card { flex-direction: row }
}This would make the card horizontal at 768px viewport — but the sidebar card becomes horizontal too, even though it only has 200px of space. The card overflows or looks broken. There's no way to fix this with media queries without adding extra classes, JavaScript, or duplicated CSS rules for each placement context.
Container queries solve this by asking "how wide is the element I'm inside?" instead of "how wide is the window?":
@container (min-width: 320px) { .card { flex-direction: row
} }The sidebar's container is 200px → card stays vertical. The main column container is 800px → card goes horizontal. Same component. Same CSS. Zero context-specific code.
container-type establishes
an element as a query container and determines which
dimensions can be queried:inline-size: enables queries on the inline dimension (width in
left-to-right writing). The element's block size (height) is
still determined by its content — normal flow behaviour.size: enables queries on both width AND height. However, it
requires the element to have a definite size in both
dimensions. If you set
container-type: size on an
element with height determined by content, it collapses to
zero height because the browser needs containment in that
dimension to query it.This is why
inline-size is
the default choice for almost all real-world use cases. Use
size only when you're
querying height too and can guarantee the container has a
defined height.
@container (condition)
queries the nearest ancestor that is a query
container. This works fine when there's only one relevant
container.Named containers let you target a specific ancestor — not just the nearest one:
.sidebar { container: sidebar / inline-size; }@container sidebar (min-width: 200px) { .widget { … }
}You need named containers when:
1. Multiple nested containers: a card inside a sidebar inside a main container — the card can query either the sidebar or the main content
2. Skipping intermediate containers: you want a deeply nested element to respond to a grandparent container, not its direct parent
3. Multiple components on the same page: two different container types coexist (sidebar, main-content) and components need to respond differently to each
One element can have multiple names (space-separated) to be targeted by different queries.
vw (viewport width unit)
is always 1% of the browser viewport width — the full window.
If you use
font-size: 4vw inside a
200px sidebar on a 1440px screen, you get 57.6px — far too
large.cqi (container query
inline) is 1% of the nearest container's inline (width)
dimension. The same
font-size: 4cqi inside a
200px sidebar gives 8px — sized appropriately for its
container.This makes container query units ideal for responsive typography and spacing inside components:
font-size: clamp(0.875rem, 3cqi, 1.5rem)— Scales with the container width (not viewport)
— Bounded by readable rem values
Available units:
cqi (inline),
cqb (block/height),
cqw (width explicit),
cqh (height explicit),
cqmin,
cqmax.
Container queries are ideal for:
— Component-level responsive design (card, nav, widget)
— Reusable design system components
— Anything where placement context matters
Media queries are still needed for:
— Overall page layout (switching from 1-column to 2-column at a breakpoint)
— Root font-size adjustments
— Navigation that depends on viewport (mobile menu)
— Environment queries:
prefers-color-scheme,
prefers-reduced-motion,
print— Cases where no parent container can be designated (top-level elements)
The modern approach is to use media queries for macro layout and container queries for component-level responsiveness. They are complementary, not competing.
container-type: inline-size
go in the HTML structure?
@media (min-width: 400px)
and
@container (min-width: 400px)?
50cqi mean?
container-type: inline-size
preferred over size in
most cases?
- Container queries respond to a parent element's size. Media queries respond to the viewport. Container queries enable truly reusable components that adapt to their placement.
-
Two steps: (1) mark the PARENT with
container-type: inline-size, then (2) write@container (condition) { … }rules for the children inside it. -
container-type values:
inline-size(width queries — most common),size(both dimensions — needs explicit height),normal(default, no querying). -
container-name: give a container a name (
container: sidebar / inline-size) so@container sidebar (…)targets that specific container, not just the nearest one. -
Shorthand:
container: name / type. With name:container: card / inline-size. Without name:container: inline-size. -
Container query units:
cqi(inline),cqb(block),cqw,cqh,cqmin,cqmax— like vw/vh but relative to the container. Ideal for fluid component typography:font-size: clamp(1rem, 3cqi, 1.5rem). - Not a replacement for media queries: use media queries for page layout and environment queries; use container queries for component-level responsiveness. They complement each other.
- Browser support: all major browsers since 2023 (Chrome 106, Firefox 110, Safari 16).
Rate Us on Google
Join Our Learning Community
Connect with thousands of learners, get daily tips, ask questions and stay updated with new tutorials.