Copyright © 2014 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
Media Queries Level 4 describes the mechanism and syntax of media queries, media types, and media features. It extends and supersedes the features defined in Media Queries Level 3. CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, in speech, etc.
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.
The (archived) public mailing list www-style@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “mediaqueries” in the subject, preferably like this: “[mediaqueries] …summary of comment…”
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 section is not normative.
HTML4 [HTML401] defined a mechanism to support media-dependent style sheets, tailored for different media types. For example, a document may use different style sheets for screen and for print. In HTML, this can be written as:
<link rel="stylesheet" type="text/css" media="screen" href="style.css"> <link rel="stylesheet" type="text/css" media="print" href="print.css">
CSS adapted and extended this functionality with its @media and @import rules, adding the ability to query the value of individual features:
@media screen {
* { font-family: sans-serif }
}
Similarly, stylesheets can be conditionally imported based on media queries:
@import "print-styles.css" print;
Media queries can be used with HTML, XHTML, XML [XMLSTYLE] and the @import and @media rules of CSS.
<link media="screen and (color), projection and (color)"
rel="stylesheet" href="example.css">
<link media="screen and (color), projection and (color)"
rel="stylesheet" href="example.css" />
<?xml-stylesheet media="screen and (color), projection and (color)"
rel="stylesheet" href="example.css" ?>
@import url(example.css) screen and (color), projection and (color);
@media screen and (color), projection and (color) { … }
Note: The [XMLSTYLE] specification has not yet been updated to
use media queries in the media pseudo-attribute.
This module replaces and extends the Media Queries, Media Type and Media Features defined in [CSS21] sections 7 and in [MEDIAQ].
Value types not defined in this specification, such as <integer>, <number> or <resolution>, are defined in [CSS3VAL]. Other CSS modules may expand the definitions of these value types.
This specification also introduces some new value types.
The <ratio> value type is a positive (not zero or negative) <integer> followed by optional whitespace, followed by a solidus ('/'), followed by optional whitespace, followed by a positive <integer>. <ratio>s can be ordered or compared by transforming them into the number obtained by dividing their first <integer> by their second <integer>.
Reasonable to restrict <ratio> to <integer>s? I’ve seen aspect ratios written with decimal points in real life.
The <mq-boolean> value type is an <integer> with the value 0 or 1. Any other integer value is invalid. Note that -0 is always equivalent to 0 in CSS, and so is also accepted as a valid <mq-boolean> value.
The units used in media queries are the same as in other parts of CSS, as defined in [CSS3VAL]. For example, the pixel unit represents CSS pixels and not physical pixels.
Relative units in media queries are based on the initial value, which means that units are never based on results of declarations. For example, in HTML, the em unit is relative to the initial value of font-size, defined by the user agent or the user’s preferences, not any styling on the page.
A media query is a method of testing certain aspects of the user agent or device that the document is being displayed in. Media queries are (almost) always independent of the contents of the document, its styling, or any other internal aspect; they’re only dependent on “external” information unless another feature explicitly specifies that it affects the resolution of Media Queries, such as the @viewport rule.
The syntax of a media query consists of an optional media query modifier, an optional media type, and zero or more media features:
A media query is a logical expression that is either true or false. A media query is true if:
Statements regarding media queries in this section assume the syntax section is followed. Media queries that do not conform to the syntax are discussed in the error handling section. I.e. the syntax takes precedence over requirements in this section.
<link rel="stylesheet" media="screen and (color)" href="example.css" />
This example expresses that a certain style sheet
(example.css) applies to devices of a certain media type
(screen) with certain feature (it must be a color screen).
Here is the same media query written in an @import-rule in CSS:
@import url(example.css) screen and (color);
User agents should re-evaluate media queries in response to changes in the user environment, for example if the device is tiled from landscape to portrait orientation, and change the behavior of any constructs dependent on those media queries accordingly.
Unless another feature explicitly specifies that it affects the resolution of Media Queries, it is never necessary to apply a style sheet in order to evaluate expressions.
Note: CSS Device Adaptation [CSS-DEVICE-ADAPT]] defines how @viewport rules interact with Media Queries.
Several media queries can be combined into a comma-separated media query list.
A media query list is true if any of its component media queries are true, and false only if all of its component media queries are false.
@media screen and (color), projection and (color) { … }
An empty media query list evaluates to true.
@media all { … }
@media { … }
A media query may optionally be prefixed by a single media query modifier, which is a single keyword which alters the meaning of the following media query.
An individual media query can have its result negated by prefixing it with the keyword not. If the media query would normally evaluate to true, prefixing it with not makes it evaluate to false, and vice versa.
<link rel="stylesheet" media="not screen and (color)" href="example.css" />
The concept of media queries originates from HTML4 [HTML401]. That specification only defined media types, but had a forward-compatible syntax that accommodated the addition of future concepts like media features: it would consume the characters of a media query up to the first non-alphanumeric character, and interpret that as a media type, ignoring the rest. For example, the media query screen and (color) would be truncated to just screen.
Unfortunately, this means that legacy user agents using this error-handling behavior will ignore any media features in a media query, even if they’re far more important than the media type in the query. This can result in styles accidentally being applied in inappropriate situations.
To hide these media queries from legacy user agents, the media query can be prefixed with the keyword only. The only keyword has no effect on the media query’s result, but will cause the media query to be parsed by legacy user agents as specifying the unknown media type “only”, and thus be ignored.
<link> element
will not be used by legacy user agents,
even if they would normally match the screen media type.
<link rel="stylesheet" media="only screen and (color)" href="example.css" />
Note: Note that the only keyword can only be used before a media type. A media query consisting only of media features, or one with another media query modifier like not, will be treated as false by legacy user agents automatically.
Note: At the time of publishing this specification, such legacy user agents are extremely rare, and so using the only modifier is rarely, if ever, necessary.
A media type is a broad category of user-agent devices
on which a document may be displayed.
The original set of media types were defined in HTML4,
for the media attribute on <link> elements.
Unfortunately, media types have proven insufficient as a way of discriminating between devices with different styling needs. Some categories which were originally quite distinct, such as screen and handheld, have blended significantly in the years since their invention. Others, such as tty or tv, expose useful differences from the norm of a full-featured computer monitor, and so are potentially useful to target with different styling, but the definition of media types as mutually exclusive makes it difficult to use them in a reasonable manner; instead, their exclusive aspects are better expressed as media features such as grid or scan.
As such, the following media types are defined for use in media queries:
In addition, the following deprecated media types are defined. Authors must not use these media types; instead, it is recommended that they select appropriate media features that better represent the aspect of the device that they are attempting to style against.
User agents must recognize the following media types as valid, but must make them match nothing.
Note: It is expected that all of the media types will also be deprecated in time, as appropriate media features are defined which capture their important differences.
A media feature is a more fine-grained test than media types, testing a single, specific feature of the user agent or display device.
Syntactically, media features resemble CSS properties: they consist of a feature name, a colon, and a value to test for. They may also be written in boolean form as just a feature name, or in range form with a comparison operator.
There are, however, several important differences between properties and media features:
If a media feature does not apply to the device where the UA is running, that media feature will always be false.
<link media="speech and (device-aspect-ratio: 16/9)"
rel="stylesheet" href="example.css">
Every media feature defines its “type” as either “range” or “discrete” in its definition table.
“Discrete” media features,
like light-level or scripting,
take their values from a set.
The values may be keywords
or boolean numbers (0 and 1),
but the common factor is that there’s no intrinsic “order” to them— “Range” media features like width, on the other hand,
take their values from a range.
Any two values can be compared to see which is lesser and which is greater.
The only significant difference between the two types is that “range” media features
can be evaluated in a range context
and accept “min-” and “max-” prefixes on their name.
Doing either of these changes the meaning of the feature— On the other hand, (width: 600px) by itself is only true
when the viewport’s width is exactly 600px.
If it’s less or greater than 600px, it’ll be false.
While media features normally have a syntax similar to CSS properties,
they can also be written more simply as just the feature name,
like (color).
When written like this, the media feature is evaluated in a boolean context.
If the feature would be true for the number 0,
a dimension with the value 0,
or the keyword none,
the media feature evaluates to false.
If it would be true for any values other than the above,
it evaluates to true.
Otherwise, it evaluates to false.
Note: The “trichotomy” above allows for correct handling of MQs as false when on devices where they don’t apply at all,
such as scan on a speech device.
For example, scripting is typically written as (scripting) to test if scripting is enabled,
or not (scripting) to see if it’s disabled.
It can still be given an explicit value as well,
with (scripting: enabled) equal to (scripting),
and (scripting: none) equal to not (scripting).
For example, (pointer) is useful,
as pointer has a none value to indicate there’s no pointing device at all on the device.
On the other hand, (scan) is just always true or always false
(depending on whether it applies at all to the device),
as there’s no value that means “false”.
Media features with a “range” type can be alternately written in a range context
that takes advantage of the fact that their values are ordered,
using ordinary mathematical comparison operators:
The basic form,
consisting of a feature name,
a comparison operator,
and a value,
returns true if the relationship is true.
The remaining forms,
with the feature name nested between two value comparisons,
returns true if both comparisons are true.
Rather than evaluating a “range” type media feature in a range context,
as described above,
the feature may be written as a normal media feature,
but with a “min-” or “max-” prefix on the feature name.
This is equivalent to evaluating the feature in a range context,
as follows:
“Discrete” type properties do not accept “min-” or “max-” prefixes.
Adding such a prefix to a “discrete” type media feature simply results in an unknown feature name.
Informal descriptions of the media query syntax appear in the prose and railroad diagrams in previous sections.
The formal media query syntax is described in this section,
with the rule/property grammar syntax defined in [CSS3SYN] and [CSS3VAL].
To parse a <media-query-list> production,
parse a comma-separated list of component values,
then parse each entry in the returned list as a <media-query>.
Its value is the list of <media-query>s so produced.
Note: This explicit definition of <media-query-list> parsing
is necessary to make the error-recovery behavior of media query lists well-defined.
The <media-type> production does not include the keywords only, not, and, and or.
A <dimension> is a dimension.
An <ident> is an identifier.
No whitespace is allowed between the "<" or ">" <delim-token>s and the following "=" <delim-token>,
if it’s present.
Whitespace must be present between a ')' character and a not, and, or or keyword,
and between a not, and, or or keyword and a '(' character.
When parsing the <media-in-parens> production,
the <general-enclosed> branch must only be chosen if the input does not match either of the preceding branches.
<general-enclosed> exists to allow for future expansion of the grammar in a reasonably compatible way.
In addition to conforming to the syntax, each media query needs to use
media types and media features according to their respective specification
in order to be considered conforming.
Each of the major terms of <media-condition> is associated with a boolean result, as follows:
Authors must not use <general-enclosed> in their stylesheets.
It exists only for future-compatibility,
so that new syntax additions do not invalidate too much of a <media-condition> in older user agents.
A media query that does not match the grammar in the previous section must be replaced by not all during parsing.
Note: Note that a grammar mismatch does not wipe out an entire media query list,
just the problematic media query.
The parsing behavior defined above automatically recovers at the next top-level comma.
Both of the above media query lists are turned into not all, speech during parsing,
which has the same truth value as just speech.
An unknown <media-type> must be treated as not matching.
But not unknown is true, as the not negates the false media type.
An unknown <mf-name> or <mf-value>, or disallowed <mf-value>,
must make the entire <media-query> be replaced by not all.
As max-weight is an unknown media feature,
this media query list is turned into not all, (color),
which is equivalent to just (color).
The orientation feature does not accept prefixes,
so this is considered an unknown media feature,
and turned into not all.
The media query test;,all is, parsed by itself,
equivalent to not all, all, which is always true.
However, CSS’s parsing rules cause the @media rule,
and thus the media query,
to end at the semicolon.
The remainder of the text is treated as a style rule
with an invalid selector and contents.
The width media feature describes the width of the targeted display area of the output device.
For continuous media, this is the width of the viewport
(as described by CSS2, section 9.1.1 [CSS21])
including the size of a rendered scroll bar (if any).
For paged media, this is the width of the page box
(as described by CSS2, section 13.2 [CSS21]).
A specified <length> cannot be negative.
The height media feature describes the height of the targeted display area of the output device.
For continuous media, this is the height of the viewport including the size of a rendered scroll bar (if any).
For paged media, this is the height of the page box.
A specified <length> cannot be negative.
The aspect-ratio media feature is defined as the ratio of the value of the width media feature
to the value of the height media feature.
The orientation media feature is portrait
when the value of the height media feature is greater than or equal to
the value of the width media feature.
Otherwise orientation is landscape.
The device-width media feature describes the width of the rendering surface of the output device.
For continuous media, this is the width of the screen.
For paged media, this is the width of the page sheet size.
A specified <length> cannot be negative.
In the example above, the style sheet will apply only to screens
less than 800px in length.
The px unit is of the logical kind,
as described in the Units section.
Note: If a device can be used in multiple orientations,
such as portrait and landscape,
the device-* media features reflect the current orientation.
The device-height media feature describes the height of the rendering surface of the output device.
For continuous media, this is the height of the screen.
For paged media, this is the height of the page sheet size.
A specified <length> cannot be negative.
In the example above, the style sheet will apply only to screens
taller than 600 vertical pixels.
Note that the definition of the px unit is the same as in other parts of CSS.
The 'device-aspect-ratio media feature is defined as the ratio of
the value of the device-width media feature to
the value of the 'device-height media feature.
The resolution media feature describes the resolution of the output device,
i.e. the density of the pixels,
taking into account the page zoom
but assuming a pinch zoom of 1.0.
When querying devices with non-square pixels,
in min-resolution queries the least-dense dimension must be compared to the specified value
and in max-resolution queries the most-dense dimensions must be compared instead.
A resolution query that’s not evaluated in a range context never matches a device with non-square pixels.
Figure out how to make the above work properly for </> syntax.
Just translate it over directly?
That prevents you from doing a "less than/greater than" dichotomy without using not.
Hmm.
For printers, this corresponds to the screening resolution
(the resolution for printing dots of arbitrary color).
Printers might have a different resolution for grayscale printing.
Another media feature should probably be added to deal with the type of resolution authors want to know to deal with monochrome printing.
This media query is equivalent, but uses the CSS cm unit:
The scan media feature describes the scanning process of some output devices.
When displaying on interlaced screens,
authors should avoid very fast movement across the screen to avoid “combing”,
and should ensure that details on the screen are wider than 1px to avoid “twitter”.
Most modern screens, and all computer screens, use progressive rendering.
The grid media feature is used to query whether the output device is grid or bitmap.
If the output device is grid-based
(e.g., a "tty" terminal, or a phone display with only one fixed font),
the value will be 1.
Otherwise, the value will be 0.
The update-frequency media feature is used to query the ability of the output device
to modify the apearance of content once it has been rendered.
It accepts the following values:
The overflow-block media feature describes the behavior of the device
when content overflows the viewport in the block axis.
“Viewport” isn’t the right term here, or in overflow-inline.
The overflow-inline media feature describes the behavior of the device
when content overflows the viewport in the inline axis.
Note: There are no known implementations of paged overflow of inline-overflowing content,
and the very concept doesn’t seem to make much sense,
so there is intentionally no paged value for overflow-inline.
The color media feature describes the number of bits per color component of the output device.
If the device is not a color device, the value is zero.
A specified <integer> cannot be negative.
If different color components are represented by different number of bits,
the smallest number is used.
In a device with indexed colors,
the minimum number of bits per color component in the lookup table is used.
Note: The described functionality is only able to describe color capabilities at a superficial level.
If further functionality is required,
RFC2531 [RFC2531] provides more specific media features which may be supported at a later stage.
The color-index media feature describes the number of entries in the color lookup table of the output device.
If the device does not use a color lookup table, the value is zero.
A specified <integer> cannot be negative.
The monochrome media feature describes the number of bits per pixel in a monochrome frame buffer.
If the device is not a monochrome device,
the output device value will be 0.
A specified <integer> cannot be negative.
The pointer media feature is used to query about the presence and accuracy of a pointing device such as a mouse.
If a device has multiple input mechanisms,
it is recommended that the UA reports the characteristics of the least capable pointing device of the primary input mechanisms;
if there are multiple reasonable "primary" input mechanisms with different characteristics,
UAs may make the feature match multiple values.
This media query takes the following values:
Both coarse and fine indicate the presence of a pointing device,
but differ in accuracy.
A pointing device with which it would be difficult or impossible
to reliably pick one of several small adjacent targets at a zoom factor of 1
would qualify as coarse.
Changing the zoom level does not affect the value of this media feature.
Note: As the UA may provide the user with the ability to zoom,
or as secondary pointing devices may have a different accuracy,
the user may be able to perform accurate clicks even if the value of this media feature is coarse.
This media feature does not indicate that the user will never be able to click accurately,
only that it is inconvenient for them to do so.
Authors are expected to react to a value of coarse
by designing pages that do not rely on accurate clicking to be operated.
For accessibility reasons,
even on devices whose pointing device can be described as fine,
the UA may give a value of coarse or none to this media query,
to indicate that the user has difficulties manipulating the input device accurately or at all.
The hover media feature is used to query whether primary pointing system
used on the output device can hover or not.
If a device has multiple pointing devices,
some of which support hovering and some of which not,
it is recommended that the UA reports the hovering ability of the least capable of the primary pointing devices.
Authors should therefore be careful not to assume that the ':hover' pseudo class
will never match on device where 'hover:none' is true,
but they should design layouts that do not depend on hovering to be fully usable.
For accessibility reasons, even on devices that do support hovering,
the UA may give a value of hover: none to this media query,
to opt into layouts that work well without hovering.
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:
User agents should set the thresholds between the 3 levels
in a way that takes into account the characteristics of the device.
For accessibility purposes, user agents may offer manual controls
allowing the user to switch between the 3 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?
Also, the high-contrast media feature could be extended to also cover inverted colors,
as discussed in http://lists.w3.org/Archives/Public/www-style/2013Oct/0672.html
The scripting media feature is used to query whether scripting languages,
such as JavaScript,
are supported on 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
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.
Is there a use-case for distinguishing between "UA doesn’t support scripting" and "scripting is supported, but turned off"?
How much is actually useful for styling?
MQ for detecting if the device is willing to display/print backgrounds and other ink-hungry properties.
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:
This defines that the custom media query named by the <extension-name> represents the given <media-query-list>.
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.
The custom media query evaluates to true if the <media-query-list> it represents evaluates to true,
and false otherwise.
The CSSRule interface is extended as follows:
The CSSCustomMediaRule interface represents a @custom-media rule.
On setting the name attribute,
run the following steps:
The following changes were made to this specification since the
19 June 2012 Recomendation of Media Queries Level 3:
This specification is the product of the W3C Working Group on
Cascading Style Sheets.
Comments from
Arve Bersvendsen,
Björn Höhrmann,
Chris Lilley,
Christoph Päper,
L. David Baron,
Elika J. Etemad,
François Remy,
Melinda Grant,
Nicholas C. Zakas
Philipp Hoschka,
Rick Byers,
Rijk van Geijtenbeek,
Roger Gimson,
Sigurd Lerstad,
Simon Kissane,
Simon Pieters,
Steven Pemberton,
and Susan Lesch
improved this specification.
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 This is an example of an informative example. Informative notes begin with the word "Note" and are set apart from the
normative text with Note, this is an informative note. Conformance to this specification
is defined for three conformance classes:
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.
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 component 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. To avoid clashes with future CSS features, the CSS2.1 specification
reserves a prefixed
syntax for proprietary and experimental extensions to CSS.
Prior to a specification reaching the Candidate Recommendation stage
in the W3C process, all implementations of a CSS feature are considered
experimental. The CSS Working Group recommends that implementations
use a vendor-prefixed syntax for such features, including those in
W3C Working Drafts. This avoids incompatibilities with future changes
in the draft.
Once a specification reaches the Candidate Recommendation stage,
non-experimental implementations are possible, and implementors should
release an unprefixed implementation of any CR-level feature they
can demonstrate to be correctly implemented according to spec.
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.
No properties defined. How much is actually useful for styling?
MQ for detecting if the device is willing to display/print backgrounds and other ink-hungry properties.
A (width >= 600px) media feature is true
when the viewport’s width is 600px or more.
2.4.2
Evaluating Media Features in a Boolean Context
Some media features are designed to be written like this.
Some numeric media features, like width,
are rarely if ever useful to evaluate in a boolean context,
as their values are almost always greater than zero.
Others, like color, have meaningful zero values:
(color) is identical to (color > 0),
indicating that the device is capable of displaying color at all.
Only some of the media features that accept keywords are meaningful in a boolean context.
2.4.3
Evaluating Media Features in a Range Context
For example, (height > 600px)
(or (600px < height))
returns true if the viewport height is greater than 600px.
For example, (400px < width < 1000px) returns true if the viewport width is between 400px and 1000px
(but not equal to either).
2.4.4
Using “min-” and “max-” Prefixes On Range Features
For example,
(min-grid: 1) is invalid,
because grid is a “discrete” media feature,
and so doesn’t accept the prefixes.
(Even though the grid media feature appears to be numeric,
as it accepts the values 0 and 1.)
3
Syntax
<media-query> = <media-condition>?
| [ not | only ]? <media-type> [ and <media-condition> ]?
<media-type> = <ident>
<media-condition> = <media-not> | <media-and> | <media-or> | <media-in-parens>
<media-not> = not <media-in-parens>
<media-and> = <media-in-parens> [ and <media-in-parens> ]+
<media-or> = <media-in-parens> [ or <media-in-parens> ]+
<media-in-parens> = ( <media-condition> ) | <media-feature> | <general-enclosed>
<media-feature> = ( [ <mf-plain> | <mf-boolean> | <mf-range> ] )
<mf-plain> = <mf-name> : <mf-value>
<mf-boolean> = <mf-name>
<mf-range> = <mf-name> [ '<' | '>' ]? '='? <mf-value>
| <mf-value> [ '<' | '>' ]? '='? <mf-name>
| <mf-value> '<' '='? <mf-name> '<' '='? <mf-value>
| <mf-value> '>' '='? <mf-name> '>' '='? <mf-value>
<mf-name> = <ident>
<mf-value> = <number> | <dimension> | <ident> | <ratio>
<general-enclosed> = [ <function-token> | ( ] <any-value>* )
Only the first media query is conforming in the example below because the
"example" media type does not exist.
@media all { body { background:lime } }
@media example { body { background:red } }
3.1
Error Handling
@media (example, all,), speech { /* only applicable to speech devices */ }
@media &test, screen { /* only applicable to screen devices */ }
For example, the media query unknown is false,
as unknown is an unknown media type.
Remember that some keywords aren’t allowed as <media-type>s
and cause parsing to fail entirely:
the media query or and (color) is turned into not all during parsing,
rather than just treating the or as an unknown media type.
<link media="screen and (max-weight: 3kg) and (color), (color)"
rel="stylesheet" href="example.css" />
@media (min-orientation:portrait) { … }
The media query (color:20example) specifies an unknown value for the color media feature
and is therefore turned into not all.
This media query is turned into not all because negative lengths are not allowed for the width media feature:
@media (min-width: -100px) { … }
Note that media queries are also subject to the parsing rules of the host language.
For example, take the following CSS snippet:
@media test;,all { body { background:lime } }
4
Screen/Device Dimensions Media Features
4.1
width
Name: width For: @media Value: <length> Type: range
For example, this media query expresses that the style sheet is usable on printed output wider than 25cm:
<link rel="stylesheet" media="print and (min-width: 25cm)" href="http://…" />
This media query expresses that the style sheet is usable on devices with viewport
(the part of the screen/paper where the document is rendered)
widths between 400 and 700 pixels:
@media (min-width: 400px) and (max-width: 700px) { … }
This media query expresses that style sheet is usable if the width of the viewport is greater than 20em.
@media (min-width: 20em) { … }
4.2
height
Name: height For: @media Value: <length> Type: range 4.3
aspect-ratio
Name: aspect-ratio For: @media Value: <ratio> Type: range 4.4
orientation
Name: orientation For: @media Value: portrait | landscape Type: discrete
The following media query tests for “portrait” orientation,
like a phone held upright.
@media (orientation:portrait) { … } 4.5
device-width
Name: device-width For: @media Value: <length> Type: range
@media (device-width < 800px) { … }
We should deprecate the device-* media features.
They don’t do anything useful,
and are mostly just abused as a ghetto "phone versus desktop" media type.
We’ve now defined a number of useful MQs for differentiating devices in useful ways instead.
4.6
device-height
Name: device-height For: @media Value: <length> Type: range
<link rel="stylesheet" media="(device-height > 600px)" />
4.7
device-aspect-ratio
Name: device-aspect-ratio For: @media Value: <ratio> Type: range
For example, if a screen device with square pixels
has 1280 horizontal pixels and 720 vertical pixels
(commonly referred to as "16:9"),
the following media queries will all match the device:
@media (device-aspect-ratio: 16/9) { … }
@media (device-aspect-ratio: 32/18) { … }
@media (device-aspect-ratio: 1280/720) { … }
@media (device-aspect-ratio: 2560/1440) { … }
5
Display Quality Media Features
5.1
resolution
Name: resolution For: @media Value: <resolution> Type: range
This media query simply detects “high-resolution” screens
(those with a hardware pixel to CSS px ratio of at least 2):
@media (resolution >= 2dppx)
For example, this media query expresses that a style sheet is usable on devices with resolution greater than 300 dots per CSS in:
@media print and (min-resolution: 300dpi) { … }
@media print and (min-resolution: 118dpcm) { … } 5.2
scan
Name: scan For: @media Value: interlace | progressive Type: discrete
For example, the “feet” of letters in serif fonts are very small features that can provoke “twitter” on interlaced devices.
The scan media feature can be used to detect this,
and use an alternative font with less chance of “twitter”:
@media (scan: interlace) { body { font-family: sans-serif; } } 5.3
grid
Name: grid For: @media Value: <mq-boolean> Type: discrete
Here is an example that detects a narrow console screen:
@media (grid) and (max-width: 15em) { … }
5.4
update-frequency
Name: update-frequency For: @media Value: none | slow | normal Type: discrete
5.5
overflow-block
Name: overflow-block For: @media Value: none | scroll | optional-paged | paged Type: discrete
5.6
overflow-inline
Name: overflow-inline For: @media Value: none | scroll Type: discrete
6
Color Media Features
6.1
color
Name: color For: @media Value: <integer> Type: range
For example, these two media queries express that a style sheet applies to all color devices:
@media (color) { … }
@media (min-color: 1) { … }
This media query expresses that a style sheet applies to color devices
with at least 8 bits per color component:
@media (color >= 8) { … }
For instance, if an 8-bit color system
represents the red component with 3 bits, the green component with 3 bits, and the blue component with 2 bits,
the color media feature will have a value of 2.
6.2
color-index
Name: color-index For: @media Value: <integer> Type: range
For example, here are two ways to express that a style sheet applies to all color index devices:
@media (color-index) { … }
@media (color-index >= 1) { … }
This media query expresses that a style sheet applies to a color index device with 256 or more entries:
<?xml-stylesheet media="(min-color-index: 256)"
href="http://www.example.com/…" ?>
6.3
monochrome
Name: monochrome For: @media Value: <integer> Type: range
For example, this is how to express that a style sheet applies to all monochrome devices:
@media (monochrome) { … }
Express that a style sheet applies to monochrome devices with more than 2 bits per pixels:
@media (monochrome >= 2) { … }
Express that there is one style sheet for color pages and another for monochrome:
<link rel="stylesheet" media="print and (color)" href="http://…" />
<link rel="stylesheet" media="print and (monochrome)" href="http://…" />
7
Interaction Media Features
7.1
pointer
Name: pointer For: @media Value: none | coarse | fine Type: discrete
Typical examples of devices matching combinations of pointer and hover:
pointer
coarse
fine
hover
none
smartphones, touch screens
stylus-based screens (Cintiq, Wacom, etc)
hover
Nintendo Wii controller, Kinect
mouse, touch pad
/* Make radio buttons and check boxes larger if we have an inaccurate pointing device */
@media (pointer:coarse) {
input[type="checkbox"], input[type="radio"] {
min-width:30px;
min-height:40px;
background:transparent;
}
}
7.2
hover
Name: hover For: @media Value: none | on-demand | over Type: discrete
For example, on a touch screen device that can also be controlled by an optional mouse,
the hover media feature should match none,
as the primary interaction mode (touching the screen) can’t hover.
/* Only use a hover-activated drop down menu on devices that can hover. */
@media (hover) {
.menu > li {display:inline-block;}
.menu ul {display:none; position:absolute;}
.menu li:hover ul {display:block; list-style:none; padding:0;}
/* ... */
}
8
Environment Media Features
8.1
light-level
Name: light-level For: @media Value: dim | normal | washed Type: discrete
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 3 levels in terms of a measurement in lux,
for several reasons:
@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; }
}
9
Scripting Media Features
9.1
scripting
Name: scripting For: @media Value: none | initial-only | enabled Type: discrete
10
Assorted Issues
We need a media feature (or set of media features) to detect the type of keyboard available.
It should be able to distinguish between full computer keyboards, phone dial pads, tv remotes, or virtual keyboards.
As an attempt at an exhaustive list is likely to fail,
finding atomic features to decompose these into would be preferable,
but these remain to be identified.
Example sets of MQs that would match on different types of devices
http://lists.w3.org/Archives/Public/www-style/2013Mar/0448.html
What to do about the view-mode media feature?
11
Custom Media Queries
@custom-media = @custom-media <extension-name> <media-query-list> ;
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 */
11.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>
11.2
CSSOM
partial interface CSSRule {
const unsigned short CUSTOM_MEDIA_RULE = 17;
};
interface CSSCustomMediaRule : CSSRule {
attribute DOMString name;
[SameObject, PutForwards=mediaText] readonly attribute MediaList media;
};
DOMString
DOMString object
that contains the serialization of the <extension-name> defined for the associated rule.
Changes
Changes Since the Media Queries Level 3
Acknowledgments
Conformance
Document conventions
class="example",
like this:
class="note", like this:
Conformance classes
Partial implementations
Experimental implementations
Non-experimental implementations
References
Normative References
Informative References
Index
Property index
@media Descriptors
Name Value Initial Type width <length> range
height <length> range
aspect-ratio <ratio> range
orientation portrait | landscape discrete
device-width <length> range
device-height <length> range
device-aspect-ratio <ratio> range
resolution <resolution> range
scan interlace | progressive discrete
grid <mq-boolean> discrete
update-frequency none | slow | normal discrete
overflow-block none | scroll | optional-paged | paged discrete
overflow-inline none | scroll discrete
color <integer> range
color-index <integer> range
monochrome <integer> range
pointer none | coarse | fine discrete
hover none | on-demand | over discrete
light-level dim | normal | washed discrete
scripting none | initial-only | enabled discrete Issues Index
Reasonable to restrict <ratio> to <integer>s?
I’ve seen aspect ratios written with decimal points in real life.
↵
We should deprecate the device-* media features.
They don’t do anything useful,
and are mostly just abused as a ghetto "phone versus desktop" media type.
We’ve now defined a number of useful MQs for differentiating devices in useful ways instead.
↵
Figure out how to make the above work properly for </> syntax.
Just translate it over directly?
That prevents you from doing a "less than/greater than" dichotomy without using not.
Hmm.
↵
Another media feature should probably be added to deal with the type of resolution authors want to know to deal with monochrome printing.
↵
“Viewport” isn’t the right term here, or in overflow-inline.
↵
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?
Also, the high-contrast media feature could be extended to also cover inverted colors,
as discussed in http://lists.w3.org/Archives/Public/www-style/2013Oct/0672.html
↵
Is there a use-case for distinguishing between "UA doesn’t support scripting" and "scripting is supported, but turned off"?
↵
We need a media feature (or set of media features) to detect the type of keyboard available.
It should be able to distinguish between full computer keyboards, phone dial pads, tv remotes, or virtual keyboards.
As an attempt at an exhaustive list is likely to fail,
finding atomic features to decompose these into would be preferable,
but these remain to be identified.
Example sets of MQs that would match on different types of devices
↵
http://lists.w3.org/Archives/Public/www-style/2013Mar/0448.html
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>
↵