Understanding CSS Container Queries: Usage, Syntax, and Browser Compatibility

When building reusable UI components that need to adapt to various container sizes, developers often rely on npm packages, but traditional media queries only respond to viewport width, which can be insufficient for embedded or iframe scenarios.

Container queries are a newer CSS layout feature that allow styles to react to the dimensions of a parent container rather than the viewport, offering more flexible and granular responsiveness.

What Is a Container Query?

Similar to media queries, container queries use a @container rule, but they evaluate the size of the element they are attached to. The basic syntax involves the contain property to designate an element as a container and the @container at‑rule to apply conditional styles.

Media Query vs. Container Query

Media queries detect viewport width (e.g., @media (max-width: 1024px) ) and apply styles globally, while container queries detect the width/height of a specific parent element, enabling components to adjust based on their immediate context.

Simple Example

.test {
height: 1000px;
width: 100%;
background-color: #f8f6f6;
color: #1c0d0d;
display: flex;
justify-content: center;
align-items: center;
}
.test-c {
height: 100px;
width: 300px;
border: 1px solid red;
}
@media (max-width: 1024px) {
.test-c {
height: 60px;
width: 200px;
}
}

The above demonstrates a traditional media query that changes styles based on viewport width.

Container Query Syntax

Key properties:

contain – shorthand for container-type and container-name (e.g., container: name / type ).

container-type – defines what dimensions are observable (e.g., size , inline-size , block-size ).

container-name – optional identifier for the container.

@container – at‑rule similar to @media , used with conditions such as min-width , max-width , aspect-ratio , etc.

Example of a container‑type component:

.test {
container-type: size; // shorthand for container type
container-name: test-name;
resize: both;
overflow: auto;
margin: 20px;
border: 2px dashed #666;
min-width: 200px;
min-height: 200px;
background: #f0f0f0;
}
@container test-name (min-aspect-ratio: 1/1) {
.test-c {
flex-direction: row;
.left { background: #e8f5e9; ::after { content: '(container aspect‑ratio ≥ 1)'; } }
}
}
@container test-name (max-aspect-ratio: 1/1) {
.test-c {
flex-direction: column;
.right { background: #fff3e0; ::after { content: '(container aspect‑ratio < 1)'; } }
}
}

The core of the example lies in the container-type: size and container-name: test-name declarations combined with @container rules to adjust layout based on the container’s aspect ratio.

Browser Compatibility

Current support for container queries on major desktop browsers:

Browser

Supported Version

Release Year

Chrome

105

2022

Firefox

110

2023

Safari

16.4

2023

Edge

105

2022

Opera

91

2022

Samsung Internet

20

2023

Mobile browser support:

Browser

Supported Version

Release Year

Chrome for Android

105

2022

Firefox for Android

110

2023

Safari on iOS

16.4

2023

Samsung Internet for Android

20

2023

UC Browser

15.4

Partial support

QQ Browser

13.1

Partial support

Conclusion

Container queries are especially useful for building reusable components that need to adapt to the size of their parent containers, a capability that media queries cannot provide. By adding the container property to a parent element and using @container in child styles, developers can create flexible, responsive layouts that work across both desktop and mobile browsers.

Try container queries when you need nested layouts or component auto‑scaling; although there is a learning curve, mastering them can greatly simplify complex responsive design challenges.