Responsive Images Community Group W3C

Container Queries

Editor’s Draft,

This version:
Mat Marquis (Bocoup)
Version History:
Commit History
Github commits on Twitter
Join the Responsive Issues Community Group
Public Mailing List
IRC: #respimg on the W3C IRC server


Container queries allow an author to control styling based on the size of a containing element rather than the size of the user’s viewport.

Status of this document

This is an unofficial draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

Table of Contents

1. Introduction

Given a complex responsive layout, developers often require granular control over styling elements relative to the size of their parent container rather than the viewport size. Container queries allow an author to control styling based on the size of a containing element rather than the size of the user’s viewport.

1.1. Abstract

1.1.1. Limitations of Viewport-Based Media Queries ## {#mq-problems}

(This section is not normative.)

Limiting breakpoints to viewport size fundamentally conflicts with the goal of creating modular page components, often requiring a number of redundant CSS rules and complex exception cases spanning multiple viewport-based breakpoints. This problem is compounded depending on how dramatically a module adapts at each of its breakpoints. Once viewport-based breakpoints have been tuned to suit the limited and predictable number of contexts a module might occupy, adjustments to styling elsewhere on the page (layout, width, padding/margins, etc.) may cause a need to revisit a module’s viewport-based breakpoints completely, as those styles are disconnected from the context of the module itself.

1.2. When to use Container Queries

Container queries are intended for use when…

1.3. Examples of Usage

[[Inside a CSS stylesheet, one can declare that sections apply to certain media types:]]

```css .element:media( min-width: 30em ) screen {



2. Container Queries

2.1. Syntax

The formal container query syntax is described in this section, with the rule/property grammar syntax defined in [CSS3SYN] and [CSS3VAL].

3. Definitions

The following terms are used throughout this specification so they are gathered here for the readers convenience. The following list of terms is not exhaustive; other terms are defined throughout this specification.

4. Acknowledgements

A complete list of participants of the Responsive Issues Community Group is available at the W3C Community Group Website.


Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.


Normative References

Tab Atkins Jr.; Simon Sapin. CSS Syntax Module. 5 November 2013. W3C Working Draft. (Work in progress.) URL:
Håkon Wium Lie; Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 30 July 2013. CR. URL:
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: