The CSS @custom-media at-rule permits creating aliases for media queries. That is significantly precious when you’ve got lengthy or complicated media queries that you just use a number of instances throughout your codebase. The characteristic is comparable in nature to a media question model of CSS {custom} properties (CSS variables).
Syntax
The syntax for defining an alias is:
@custom-media () [ | true | false ]; For instance:
@custom-media --modern-touch (pointer: coarse) and (min-width: 1024px);…the place the dashed ident is --modern-touch.
The syntax for utilizing an alias is similar as utilizing any media question, however as an alternative of offering media varieties or media options, you present the @custom-media:
@cutom-media {
/* ... */
} Arguments and Descriptors
--), much like features or {custom} properties. Similar to {custom} properties, the title is case-sensitive. For instance,--mobile-breakpointand--Cellular-Breakpointwould seek advice from totally different {custom} media definitions.true/false: All the time-match / never-match toggles.
Let’s have a look at how these work in several contexts, reminiscent of how they’re scoped, utilizing them with booleans, defining complicated logic, setting guidelines with the CSS vary syntax, and even nesting aliases.
Scope and Placement
Not like {custom} properties, that are scoped to the ingredient they’re outlined on (and their kids), @custom-media guidelines are world. They are evaluated within the world scope of the stylesheet and can all the time apply to your complete doc. If a number of @custom-media guidelines are outlined with the identical title, the one in scope on the time of analysis is the one that’s used.
When a @media rule makes use of a {custom} alias, i.e. the dashed ident, it seems to be on the present definition of that alias at that time within the stylesheet. If the alias is redefined later, it doesn’t “replace” the media queries that have been already processed. For instance, on this case margin-block: 1rem will solely be utilized to physique whether it is fullscreen and never browser regardless of the later declaration utilizing the identical title.
@custom-media --screen-display (display-mode: fullscreen);
@media (--screen-display) {
physique {
margin-block: 1rem;
}
}
@custom-media --screen-display (display-mode: browser);Be aware: This scoping habits remains to be being mentioned and is topic to alter sooner or later.
Boolean Constants
Within the Syntax part above, be aware {that a} @custom-media rule may be explicitly set to true or false. That is helpful for “toggling” total blocks of CSS throughout growth or for characteristic flagging.
Operators and Advanced Logic
As @custom-media makes use of the very same logical operators (and, ,, or, not, solely) and grouping guidelines as @media, you’ll be able to construct complicated, parentheses-grouped logic simply as you usually would. For a full breakdown of learn how to use operators, negate options, or conceal stylesheets from older browsers, reference the Logic and Operators part of the @media almanac. It is usually price referencing the part on nesting and sophisticated decision-making when constructing complicated queries.
To, for instance, assemble a question utilizing the and logical operator, you’ll be able to write this:
@custom-media --modern-touch (pointer: coarse) and (min-width: 1024px);Vary Syntax
The identical as every other @custom-media has help for the ranged media question syntax which makes use of operators, e.g. higher than (>), lower than (<), and equals (=), to judge circumstances:
/* Previous approach */
@custom-media --tablet (min-width: 768px) and (max-width: 1024px);
/* New, cleaner approach */
@custom-media --tablet (768px <= width <= 1024px);Nested Aliases
One distinctive characteristic of @custom-media aliases is that they’ll reference one another. This lets you construct layered, semantic circumstances:
@custom-media --narrow-window (width < 30rem);
@custom-media --small-and-hover (--narrow-window) and (hover: hover);
@media (--small-and-hover) {
/* Kinds for mobile-sized screens with hover capabilities */
}Nevertheless, if a loop is detected, all concerned {custom} media queries are handled as undefined. For example, if --query-a references --query-b, then --query-b can not reference --query-a. Equally, a {custom} media question can not seek advice from itself.
Additionally concentrate on over-nesting, as that may make debugging and figuring out which layer of question is having the related affect in your browser’s developer instruments very tough.
Instance: Defining Frequent Breakpoints
As an alternative of remembering in case your “pill” breakpoint is 768px or 800px, you’ll be able to outline it as soon as on the high of your stylesheet.
@custom-media --tablet (min-width: 768px);
.sidebar {
show: none;
@media (--tablet) {
show: block;
}
}Instance: Defining Shorthands for Current Properties
Commonplace boilerplate reminiscent of (prefers-reduced-motion: scale back) can be utilized many instances throughout a codebase, and people bytes add up. You should use @custom-media to outline less complicated options:
@custom-media --prefers-reduced-motion (prefers-reduced-motion: scale back);
@media (--prefers-reduced-motion) {
/* ... */
}
@custom-media --js-enabled (scripting: enabled);
@custom-media --js-disabled (scripting: none);
@media (--js-disabled) {
.no-js-banner {
show: block;
}
}There are a large number of Open Props @custom-media Recipes you might think about using.
JavaScript Help
@custom-media aliases should not uncovered to the JavaScript matchMedia() technique, that means this code will not work, even when you’ve got the alias outlined someplace in your web page.
matchMedia("(--tablet)")Specification
The @custom-media at-rule is outlined within the Media Queries Stage 5 specification.
Browser Help
Unsupported browsers largely ignore @custom-media, so fallback declarations and progressive enhancement methods may be advantageous. You should use @helps to test if @custom-media is supported within the consumer’s browser, like so:
@helps (at-rule(@custom-media)) {
/* ... */
}Mockingly, nonetheless, at time of writing, the @helps at-rule analysis performance doesn’t have full help throughout browsers (Chrome 148+ solely), so you’ll need to test whether it is supported in your case. You’ll be able to see the dialogue on this in CSS Drafts Subject #2463.
One other strategy is to make use of a device reminiscent of PostCSS Customized Media, which can develop the principles in a construct step to realize wider browser help.
