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
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 explicitly 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.
- Devices equipped with a light sensor usually adjust the brightness of the screen automatically. Depending on the level of adjustment, the thresholds for needing a low contrast or hight contrast content may vary.
- Different screen technologies wash out at very different ambient light levels; e-ink displays remain readable in bright daylight, while liquid crystal displays do not.
- Many embedded light sensors are inaccurately calibrated, making it difficult to establish useful thresholds valid across devices.
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; }
}
2.2. Detecting the display technology: the environment-blending feature
| Name: | environment-blending |
|---|---|
| For: | @media |
| Value: | opaque | additive | subtractive |
| Type: | discrete |
The environment-blending media feature is used to query the characteristics of the user’s display so the author can adjust the style of the document. An author might choose to adjust the visuals and/or layout of the page depending on the display technology to increase the appeal or improve legibility.
The following values are valid:
- opaque
- The document is rendered on an opaque medium, such as a traditional monitor or paper. Black is dark and white is 100% light.
- additive
-
The display blends the colors of the canvas with the real world using additive mixing.
Black is fully transparent and white is 100% light.
For example: a head-up display in a car.
- subtractive
-
The display blends the colors of the canvas with the real world using subtractive mixing.
White is fully transparent and dark colors have the most contrast.
For example: an LCD display embedded in a bathroom mirror.
Is there a need for the subtractive value?
body { background-color: white; }
p { color: black; }
@media(environment-blending: additive) {
body { background-color: black; }
p { color: white; font-size: 16px; font-weight: 1000; }
}
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.
If multiple @custom-media rules declare the same <extension-name>, the truth value is based on the last one alone, ignoring all previous declarations of the same <extension-name>.
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.
@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
<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.
This value must not match if the User Agent has done some kind of content aware inversion such as one that preserves the images.
Note: This is because the goal of this media feature is to enable authors to mitigate the undesirable effects of the non content aware approach that invert all the pixels. If the author were to take counter measures even in the content-aware cases, their counter measures and the UA’s would be at risk of cancelling each other.
@media (inverted-colors) {
img { filter: invert(100%); }
* { text-shadow: none !important; box-shadow: none !important; }
}
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.
5.3. Detecting the desire for reduced transparency on the page: the prefers-reduced-transparency feature
| Name: | prefers-reduced-transparency |
|---|---|
| For: | @media |
| Value: | no-preference | reduce |
| Type: | discrete |
The prefers-reduced-transparency media feature is used to detect if the user has requested the system minimize the amount of transparent or translucent layer effects 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 transparent or translucent layer effects.
How does this interact with preferences around e.g. pattern fills and backgrounds? They’re not about transparency, but they also interfere with shape recognition.
5.4. Detecting the desire for increased or decreased color contrast from elements on the page: the prefers-contrast feature
| Name: | prefers-contrast |
|---|---|
| For: | @media |
| Value: | no-preference | high | low |
| Type: | discrete |
The prefers-contrast media feature is used to detect if the user has requested the system increase or decrease the amount of contrast between adjacent colors. For example, many users have difficulty reading text that has a small difference in contrast to the text background and would prefer a larger contrast.
- no-preference
- Indicates that the user has made no preference known to the system. This keyword value evaluates as false in the boolean context.
- high
- Indicates that user has notified the system that they prefer an interface that has a higher level of contrast.
- low
- Indicates that user has notified the system that they prefer an interface that has a lower level of contrast.
Split high into two levels, “extremely high” (as used in MSFT’s black-on-white high conrast theme) and “increased (as implemented in Apple’s Increased Contrast settings)? <https://github.com/w3c/csswg-drafts/issues/2943>
5.5. Detecting the desire for light or dark color schemes: the prefers-color-scheme feature
| Name: | prefers-color-scheme |
|---|---|
| For: | @media |
| Value: | no-preference | light | dark |
| Type: | discrete |
The prefers-color-scheme media feature reflects the user’s desire that the page use a light or dark color theme.
- no-preference
- Indicates that the user has made no preference known to the system. This keyword value evaluates as false in the boolean context.
- light
- Indicates that user has expressed the preference for a page that has a light theme (dark text on light background).
- dark
- Indicates that user has expressed the preference for a page that has a dark theme (light text on dark background).
The method by which the user expresses their preference can vary. It might be a system-wide setting exposed by the Operating System, or a setting controlled by the User Agent.
Note: User preferences can also vary by medium. For example, a user may prefer dark themes on a glowing screen, but light themes when printing (to save ink and/or because inked text on blank paper prints better than blank letterforms knocked out of an inked background). UAs are expected to take such variances into consideration so that prefers-color-scheme reflects preferences appropriate to the medium rather than preferences taken out of context.
5.6. Detecting a forced color palette: the forced-colors feature
| Name: | forced-colors |
|---|---|
| For: | @media |
| Value: | none | active |
| Type: | discrete |
The forced-colors media feature is used to detect if the user agent has enabled a forced colors mode where it enforces a user-chosen limited color palette on the page.
- none
- Forced colors mode is not active; the page’s colors are not being forced into a limited palette.
- active
- Indicates that forced colors mode is active. The UA will provide the color palette to authors through the CSS system color keywords and, if appropriate, trigger the appropriate value of prefers-color-scheme so that authors can adapt the page. See [[!css-color-adjust-1#forced]] for details.
5.7. Detecting the desire for reduced data usage when loading a page: the prefers-reduced-data feature
This feature may be an undesired source of fingerprinting, with a bias towards low income with limited data. A Privacy and Security section should be added to this spec, and it should address this concern. <https://github.com/w3c/csswg-drafts/issues/4832>
It might be useful for this feature to be more than a binary switch, and instead express different degrees of preference for limited data. <https://github.com/w3c/csswg-drafts/issues/4833>
This feature is an early draft, and the CSS-WG does not consider it ready for shipping in production. <https://github.com/w3c/csswg-drafts/issues/4834>
| Name: | prefers-reduced-data |
|---|---|
| For: | @media |
| Value: | no-preference | reduce |
| Type: | discrete |
The prefers-reduced-data media feature is used to detect if the user has a preference for being served alternate content that uses less data for the page to be rendered.
- 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 expressed the preference for lightweight alternate content.
The method by which the user expresses their preference can vary. It might be a system-wide setting exposed by the Operating System, or a setting controlled by the User Agent.
Note: User Agents may consider setting this based on the same user or system preference as they use to set the Save-Data HTTP request header.
.image {
background-image: url("images/heavy.jpg");
}
@media (prefers-reduced-data: reduce) {
/* Save-Data: On */
.image {
background-image: url("images/light.jpg");
}
}
Changes
Changes Since the Media Queries Level 4
The following additions were made to this module since the Media Queries Level 4:
- Reinstate the light-level, inverted-colors, and Custom Media Queries sections from earlier Media Queries Level 4 drafts.
- Added prefers-reduced-motion, prefers-reduced-transparency, prefers-contrast, prefers-color-scheme, and forced-colors media features.
Acknowledgments
This specification is the product of the W3C Working Group on Cascading Style Sheets.
Comments from Rossen Atanassov, James Craig, and Elika J. Etemad (fantasai) improved this specification.