CSS Container Queries
debt(d5/e3/b3/t5)
Closest to 'specialist tool catches' (d5). Stylelint and Lighthouse (from detection_hints.tools) can flag some issues, but detecting misuse—like using viewport media queries when container queries are needed—requires understanding component context. The code_pattern notes 'component styles using viewport media queries when the component may appear in different container sizes' which isn't automatically caught without semantic understanding.
Closest to 'simple parameterised fix' (e3). The quick_fix shows adding container-type to a wrapper and converting media query syntax to @container syntax. This is a localized refactor within component styles—not a one-liner, but contained within a single component's CSS. Multiple rules may need updating but the pattern is consistent.
Closest to 'localised tax' (b3). Container queries apply only to web contexts (per applies_to) and affect individual component styling decisions. Once adopted for a component, maintainers must remember the container-type requirement, but the impact is contained to components using this pattern. Not a system-wide architectural choice.
Closest to 'notable trap' (t5). The misconception explicitly states developers confuse media queries and container queries as solving the same problem. The common_mistakes reinforce this: forgetting container-type on parent (required but not obvious from @container syntax), and confusion about unnamed container matching. These are documented gotchas that most developers learn, but the initial mental model mismatch is real.
Also Known As
TL;DR
Explanation
Media queries respond to the viewport. Container queries respond to the containing element's size — the same component can render differently when used in a narrow sidebar vs a wide main column. Define a container with container-type, then use @container to write size-dependent styles. Supported in all modern browsers since 2023. Container queries solve the fundamental problem of component-level responsiveness that media queries could never address.
Common Misconception
Why It Matters
Common Mistakes
- Forgetting to set container-type on the parent — @container rules have no effect without it.
- Using container queries for page-level layout — media queries are still correct for overall page structure.
- Not naming containers when nesting — unnamed containers match the nearest container ancestor, which may be unexpected.
- Browser support assumption — container queries require 2023+ browsers; check support requirements.
Code Examples
/* Media query — can't make component respond to its container:
.card { font-size: 16px; }
@media (max-width: 600px) {
.card { font-size: 14px; } /* When viewport is small -- but card might be in a narrow column on a wide viewport */
}/* Container query — responds to parent size:
.card-wrapper {
container-type: inline-size;
container-name: card;
}
.card { font-size: 16px; display: grid; grid-template-columns: auto 1fr; }
@container card (max-width: 300px) {
.card {
font-size: 14px;
grid-template-columns: 1fr; /* Stack vertically when container is narrow */
}
}