CSS container style queries let descendants respond to a computed style on their container. Today, the practical and interoperable use is querying CSS custom properties with @container style().
This approach helps a reusable component adapt to a local theme or state without adding a different class to every child and without depending on viewport size.
Style queries and size queries solve different problems. A style query checks a container's computed style; a size query checks dimensions such as inline size.
How Container Style Queries Work
Every non-empty element can act as a style query container. You do not need container-type when the query contains only style(). The browser finds the nearest eligible ancestor and evaluates its computed custom property.
- Place a custom property on a parent container.
- Write an
@container style(--name: value)rule. - Style descendants inside the matching rule.
- Keep a normal fallback outside the query.
Container Style Query Syntax
Syntax:
/* Match descendants when the container theme is dark */
@container style(--theme: dark) {
.card {
color: white;
}
}Plain colon syntax compares the computed custom-property value. You can combine checks with and, or, and not.
Creating Theme-Aware Components
Set the theme custom property on each component wrapper. The same card markup can then adapt to different containers.
Example:
/* Containers publish their local theme */
.dark-area { --theme: dark; }
.light-area { --theme: light; }
@container style(--theme: dark) {
.card { background: #34495e; color: white; }
}Example:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>CSS Container Style Query Demo</title>
<style>
body { max-width: 760px; margin: 2rem auto; padding: 0 1rem; font-family: Arial, sans-serif; }
.gallery { display: grid; grid-template-columns: repeat(2, 1fr); gap: 1rem; }
.theme { padding: 1rem; border: 1px solid #bbb; }
.theme.dark { --theme: dark; background: #243447; }
.theme.light { --theme: light; background: #f4f6f8; }
.card { padding: 1rem; border-radius: 0.5rem; background: white; }
@container style(--theme: dark) {
.card { color: #fff; background: #34495e; border-left: 5px solid #72c7ff; }
}
@container style(--theme: light) {
.card { color: #253545; border-left: 5px solid #e7a61a; }
}
</style>
</head>
<body>
<h1>Container Style Query Themes</h1>
<div class="gallery">
<section class="theme dark">
<article class="card"><h2>Dark Card</h2><p>Styled from its container theme.</p></article>
</section>
<section class="theme light">
<article class="card"><h2>Light Card</h2><p>Uses the same card markup.</p></article>
</section>
</div>
</body>
</html>
Naming a Style Container
Use container-name when nested containers might publish the same custom property and you need to select a particular ancestor.
Example:
/* Query only the container named sidebar */
.sidebar { container-name: sidebar; --density: compact; }
@container sidebar style(--density: compact) {
.item { padding: 0.35rem; }
}Registered Custom Properties
An unregistered custom property is largely compared as written tokens. Registering it with @property gives the value a syntax and initial value, allowing equivalent computed values to compare more predictably.
Current Limitations and Fallbacks
Current style queries reliably support custom properties. Do not assume that querying ordinary declarations such as style(display: grid) works everywhere. Put essential component styling outside the query and use @supports container-style(--theme: dark) only when a targeted support check helps your fallback strategy.
Best Practices
- Use meaningful custom-property names.
- Keep component defaults outside the query.
- Name containers when nesting creates ambiguity.
- Avoid using container style queries for values better expressed by inherited properties.
- Test every supported browser and fallback.
Conclusion
CSS container style queries let a component respond to local custom-property state. Publish a value on the container, query it with style(), keep a dependable fallback, and account for today's custom-property support boundary.