Tutorials CSS Container Queries
Ch 51 / 60
Chapter 51 Advanced 10 min read CSS

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.

What you'll learn
Media queries vs container queries
container-type and container-name
@container rule syntax
Container query units: cqi, cqw, cqb
Named containers for targeting
Real-world component patterns

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:

📱 Media Query — viewport-based
Problem: Card needs to be horizontal
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.
📦 Container Query — parent-based
Solution: Card responds to
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.
Live demo — same card component, different container widths
Narrow container (~160px)
🎨
Design Course
Learn UI/UX design from scratch with real projects.
Enroll
vertical layout
Wide container (~340px)
🎨
Design Course
Learn UI/UX design from scratch with real projects.
Enroll
horizontal layout (container ≥ 260px)

↑ 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:

container-type: inline-size;
property
on the PARENT element
inline-size
enables width-based queries
@container (min-width: 400px) { … }
@container
the query rule
condition
same syntax as @media
CSS — container query setup and syntax
/* ── 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:

Same .widget — queries different named containers
sidebar container
main-content container
Analytics Dashboard
CSS — named containers
/* ── 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:

Bars below use container-relative units — they scale with this container's width
50cqi (50% of container inline)
75cqi (75% of container)
25cqi

Resize the browser — these bars track the column width, not the viewport

CSS — container query units
/* 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

✓ Container queries are ideal for
  • Card components (sidebar vs main column)
  • Media objects (image + text)
  • Nav menus (hamburger vs full)
  • Data tables (cards vs rows)
  • Design system components
⚡ Still use media queries for
  • Overall page layout breakpoints
  • Viewport-level navigation changes
  • Font size on body/root
  • Print styles
  • prefers-color-scheme, motion
CSS — production container query patterns
/* ── 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
Free Resource
CSS3 Cheat Sheet — Container Queries & Modern CSS
Complete reference covering @container, container-type, cq units and responsive patterns.
Download PDF

Try It Yourself

A resizable container demo — drag the preview pane divider to see the card component adapt based on container width, not viewport:

Live Editor
✎ Editor
👁 Preview
Featured Course — Enroll Now
Modern Web Development With AI
Master HTML, CSS, JavaScript, React and Node.js with real projects and placement support.
120+
Chapters
40 hrs
Content
10 Real
Projects
4.9 ⭐
Rating
HTML5CSS3JavaScriptReact.jsNode.jsTailwind CSSAI Tools

Quick Check — Chapter 51

Questions & Answers
The sidebar problem: a card component needs to be vertical in a 200px sidebar and horizontal in a 800px main column — but both exist on the same page at the same viewport width.

@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.
Without a name, @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.
No — they serve different purposes and work best together:

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.
Multiple Choice Questions
Question 1 of 5
Where does container-type: inline-size go in the HTML structure?
Question 2 of 5
What is the key difference between @media (min-width: 400px) and @container (min-width: 400px)?
Question 3 of 5
What does 50cqi mean?
Question 4 of 5
Why is container-type: inline-size preferred over size in most cases?
Question 5 of 5
Which rule correctly makes a card display in a row when its container is 400px wide?
Chapter Summary
  • 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).
~10 min read
Advanced level
Chapter 51 of 60

Rate Us on Google

4.8 / 5
Enjoying this tutorial?
Your 5-star review helps other learners discover our free tutorials and encourages us to keep creating quality content.
80+ reviews
Write a Google Review
Join WhatsApp Channel