Media Queries Level 5

Editor’s Draft,

This version:
https://drafts.csswg.org/mediaqueries-5/
Previous Versions:
Issue Tracking:
Inline In Spec
GitHub Issues
Editors:
Dean Jackson (Apple)
Florian Rivoal (Vivliostyle)
Tab Atkins Jr. (Google)

Abstract

Media Queries allow authors to test and query values or features of the user agent or display device, independent of the document being rendered. They are used in the CSS @media rule to conditionally apply styles to a document, and in various other contexts and languages, such as HTML and Javascript.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, in speech, etc.

Status of this document

This is a public copy of the editors’ 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.

GitHub Issues are preferred for discussion of this specification. When filing an issue, please put the text “mediaqueries-5” in the title, preferably like this: “[mediaqueries-5] …summary of comment…”. All issues and comments are archived, and there is also a historical archive.

This document was produced by the CSS Working Group (part of the Style Activity).

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2017 W3C Process Document.

Once complete, this specification will include and extend Media Queries Level 4. [MEDIAQUERIES-4]

1. Introduction

Note: At the time of writing, [MEDIAQUERIES-4] is not completely finalized yet. To avoid accidental divergences and maintenance overhead, This specification is written as a delta specification over Media Queries Level 4. Once the level 4 specification is final, its content will be integrated into this specification, which will then replace it. Until then, Media Queries Level 5 only contains additions and extensions to level 4.

1.1. Media Features

Copy level 4 prose when final

1.1.1. Evaluating Media Features in a Boolean Context

Copy level 4 prose when final, except the following paragraph which is changed compared to level 4.

When written like this, the media feature is evaluated in a boolean context. If the feature would be true for any value other than the number 0, a <dimension> with the value 0, the keyword none, or a value explicitely defined by that media feature to evaluate as false in a boolean context, the media feature evaluates to true. Otherwise, it evaluates to false.

2. Environment Media Features

2.1. Detecting the ambient light level: the light-level feature

Name: light-level
For: @media
Value: dim | normal | washed
Type: discrete

The light-level media feature is used to query about the ambient light-level in which the device is used, to allow the author to adjust style of the document in response. The following values are valid:

dim
The device is used in a dim environment, where excessive contrast and brightness would be distracting or uncomfortable to the reader. For example: night time, or a dimly illuminated indoor environment.
normal
The device is used in a environment with a light level in the ideal range for the screen, and which does not necessitate any particular adjustment.
washed
The device is used in an exceptionally bright environment, causing the screen to be washed out and difficult to read. For example: bright daylight.

User agents should set the thresholds between the three levels in a way that takes into account the characteristics of the device.

Even though it is expected that User Agents will adjust the value of this media feature based on ambient light sensors, this specification intentionally refrains from defining the three levels in terms of a measurement in lux, for several reasons:

For accessibility purposes, user agents may offer manual controls allowing the user to switch between the three levels of independently of the ambient light level, as high contrast or low contrast styles may be more suitable for users with visual disabilities.

Using this media feature for accessibility purposes overlaps a lot with the high-contrast media feature proposed by Microsoft. Can we adjust this so that it covers all use cases for both, or somehow modify them to work in an orthogonal, rather than overlapping, fashion?

@media (light-level: normal) {
  p { background: url("texture.jpg"); color: #333 }
}
@media (light-level: dim) {
  p { background: #222; color: #ccc }
}
@media (light-level: washed) {
  p { background: white; color: black; font-size: 2em; }
}

3. Scripting Media Features

3.1. Scripting Support: the scripting feature

Name: scripting
For: @media
Value: none | initial-only | enabled
Type: discrete

The scripting media feature is used to query whether scripting languages, such as JavaScript, are supported on the current document.

enabled
Indicates that the user agent supports scripting of the page, and that scripting in the current document is enabled for the lifetime of the document.
initial-only
Indicates that the user agent supports scripting of the page, and that scripting in the current document is enabled during the initial page load, but is not supported afterwards. Examples are printed pages, or pre-rendering network proxies that render a page on a server and send a nearly-static version of the page to the user.

Should there be an explicit minimum threshold to meet before a UA is allowed to claim initial-only? Having one would mean authors would know what they can depend on, and could tailor their scripts accordingly. On the other hand, pinpointing that threshold is difficult: if it is set too low, the scripting facilities that authors can depend on may be to constrained to be practical, even though actual UAs may potentially all support significantly more. But trying to set it higher may cause us to exclude UAs that do support scripting at loading time, but restrict it in some cases based on complex heuristics. For instance, conservative definitions likely include at least running all inline scripts and firing the DOMContentLoaded event. But it does not seem useful for authors to constrain themselves to this if most (or maybe all) initial-only UAs also load external scripts (including async and defer) and fire the load event. On the other hand, requiring external scripts to be loaded and the load event to be fired could exclude UAs like Opera mini, which typically do run them, but may decide not to based on timeouts and other heuristics. <https://github.com/w3c/csswg-drafts/issues/503>

none
Indicates that the user agent will not run scripts for this document; either it doesn’t support a scripting language, or the support isn’t active for the current document.

Some user agents have the ability to turn off scripting support on a per script basis or per domain basis, allowing some, but not all, scripts to run in a particular document. The scripting media feature does not allow fine grained detection of which script is allowed to run. In this scenario, the value of the scripting media feature should be enabled or initial-only if scripts originating on the same domain as the document are allowed to run, and none otherwise.

Note: A future level of CSS may extend this media feature to allow fine-grained detection of which script is allowed to run.

4. Custom Media Queries

When designing documents that use media queries, the same media query may be used in multiple places, such as to qualify multiple @import statements. Repeating the same media query multiple times is an editing hazard; an author making a change must edit every copy in the same way, or suffer from difficult-to-find bugs in their CSS.

To help ameliorate this, this specification defines a method of defining custom media queries, which are simply-named aliases for longer and more complex media queries. In this way, a media query used in multiple places can instead be assigned to a custom media query, which can be used everywhere, and editing the media query requires touching only one line of code.

A custom media query is defined with the @custom-media rule:

@custom-media = @custom-media <extension-name> [ <media-query-list> | true | false ] ;

The <extension-name> can then be used in a media feature. It must be used in a boolean context; using them in a normal or range context is a syntax error. If a <media-query-list> is given, the custom media query evaluates to true if the <media-query-list> it represents evaluates to true, and false otherwise. If true or false is given, the custom media query evaluates to true or false, respectively.

A @custom-media rule can refer to other custom media queries. However, loops are forbidden, and a custom media query must not be defined in terms of itself or of another custom media query that directly or indirectly refers to it. Any such attempt of defining a custom media query with a circular dependency must cause all the custom media queries in the loop to fail to be defined.

Note: For error handling purposes, an undefined media feature is different from a media feature that evaluates to false. See Media Queries 4 §3.2 Error Handling for details.

For example, if a responsive site uses a particular breakpoint in several places, it can alias that with a reasonable name:
@custom-media --narrow-window (max-width: 30em);

@media (--narrow-window) {
  /* narrow window styles */
}
@media (--narrow-window) and (script) {
  /* special styles for when script is allowed */
}
/* etc */

4.1. Script-based Custom Media Queries

Define a map of names to values for JS. Values can be either a MediaQueryList object or a boolean, in which case it’s treated identically to the above, or can be a number or a string, in which case it’s treated like a normal MQ, and can use the normal or range context syntax. Like:
<script>
CSS.customMedia.set('--foo', 5);
</script>
<style>
@media (_foo: 5) { ... }
@media (_foo < 10) { ... }
</style>

5. User Preference Media Features

5.1. Detecting the desire for inverted colors on the display: the inverted-colors feature

Name: inverted-colors
For: @media
Value: none | inverted
Type: discrete

The inverted-colors media feature indicates whether the content is displayed normally, or whether colors have been inverted.

Note: This is an indication that the user agent or underlying operating system has forcibly inverted all colors, not a request to do so. This is sometimes provided as a simple accessibility feature, allowing users to switch between light-on-dark and dark-on-light text. However, this has unpleasant side effects, such as inverting pictures, or turning shadows into highlights, which reduce the readability of the content.

none
Colors are displayed normally.
inverted
All pixels within the displayed area have been inverted.
For example, a user frequently using their operating system’s ability to invert the screens color may want to add the following to their user style sheet, to limit the undesirable side effects of the inversion.
@media (inverted-colors) {
  img { filter: invert(100%); }
  * { text-shadow: none; box-shadow: none; }
}

5.2. Detecting the desire for less motion on the page: the prefers-reduced-motion feature

Name: prefers-reduced-motion
For: @media
Value: no-preference | reduce
Type: discrete

The prefers-reduced-motion media feature is used to detect if the user has requested the system minimize the amount of animation or motion it uses.

no-preference
Indicates that the user has made no preference known to the system. This keyword value evaluates as false in the boolean context.
reduce
Indicates that user has notified the system that they prefer an interface that minimizes the amount of movement or animation, preferably to the point where all non-essential movement is removed.

Changes

Changes Since the Media Queries Level 4

The following changes were made to this specification since the 6 July 20126 Working Draft of Media Queries Level 4:

Acknowledgments

This specification is the product of the W3C Working Group on Cascading Style Sheets.

Comments from James Craig improved this specification.

Conformance

Document conventions

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.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Requirements for Responsible Implementation of CSS

The following sections define several conformance requirements for implementing CSS responsibly, in a way that promotes interoperability in the present and future.

Partial Implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported property values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Implementations of CR-level Features

Once a specification reaches the Candidate Recommendation stage, implementers should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec, and should avoid exposing a prefixed variant of that feature.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-CASCADE-3]
Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 3. URL: https://www.w3.org/TR/css-cascade-3/
[CSS-CONDITIONAL-3]
CSS Conditional Rules Module Level 3 URL: https://www.w3.org/TR/css3-conditional/
[CSS-EXTENSIONS]
Tab Atkins Jr.. CSS Extensions. ED. URL: https://drafts.csswg.org/css-extensions/
[CSS-VALUES-3]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. URL: https://www.w3.org/TR/css-values-3/
[MEDIAQUERIES-4]
Florian Rivoal; Tab Atkins Jr.. Media Queries Level 4. URL: https://www.w3.org/TR/mediaqueries-4/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

Property Index

No properties defined.

@media Descriptors

Name Value Initial Type
light-level dim | normal | washed discrete
scripting none | initial-only | enabled discrete
inverted-colors none | inverted discrete
prefers-reduced-motion no-preference | reduce discrete

Issues Index

Copy level 4 prose when final
Copy level 4 prose when final, except the following paragraph which is changed compared to level 4.
Using this media feature for accessibility purposes overlaps a lot with the high-contrast media feature proposed by Microsoft. Can we adjust this so that it covers all use cases for both, or somehow modify them to work in an orthogonal, rather than overlapping, fashion?
Should there be an explicit minimum threshold to meet before a UA is allowed to claim initial-only? Having one would mean authors would know what they can depend on, and could tailor their scripts accordingly. On the other hand, pinpointing that threshold is difficult: if it is set too low, the scripting facilities that authors can depend on may be to constrained to be practical, even though actual UAs may potentially all support significantly more. But trying to set it higher may cause us to exclude UAs that do support scripting at loading time, but restrict it in some cases based on complex heuristics. For instance, conservative definitions likely include at least running all inline scripts and firing the DOMContentLoaded event. But it does not seem useful for authors to constrain themselves to this if most (or maybe all) initial-only UAs also load external scripts (including async and defer) and fire the load event. On the other hand, requiring external scripts to be loaded and the load event to be fired could exclude UAs like Opera mini, which typically do run them, but may decide not to based on timeouts and other heuristics. <https://github.com/w3c/csswg-drafts/issues/503>
Define a map of names to values for JS. Values can be either a MediaQueryList object or a boolean, in which case it’s treated identically to the above, or can be a number or a string, in which case it’s treated like a normal MQ, and can use the normal or range context syntax. Like:
<script>
CSS.customMedia.set('--foo', 5);
</script>
<style>
@media (_foo: 5) { ... }
@media (_foo < 10) { ... }
</style>