@custom-media | CSS-Tips

The CSS @custom-media at-rule permits creating aliases for media queries. That is significantly helpful in case you have lengthy or advanced media queries that you just use a number of instances throughout your codebase. The characteristic is analogous in nature to a media question model of CSS {custom} properties (CSS variables).

Syntax

The syntax for defining an alias is:

@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 a substitute of offering media sorts or media options, you present the of your outlined @custom-media:

@media  {
  /* ... */
}

Arguments and Descriptors

• : A user-defined identifier that should begin with two dashes (--), much like features or {custom} properties. Similar to {custom} properties, the identify is case-sensitive. For instance, --mobile-breakpoint and --Cell-Breakpoint would seek advice from completely different {custom} media definitions.
• : An inventory of media queries, separated by operators.
• true/false: At all times-match / never-match toggles.

Let’s take a look at how these work in several contexts, comparable to how they’re scoped, utilizing them with booleans, defining advanced 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 at all times apply to your complete doc. If a number of @custom-media guidelines are outlined with the identical identify, 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 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 identify.

@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 conduct continues to be being mentioned and is topic to alter sooner or later.

Boolean Constants

Within the Syntax part above, notice {that a} @custom-media rule could be explicitly set to true or false. That is helpful for “toggling” complete blocks of CSS throughout improvement or for characteristic flagging.

Operators and Complicated 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 advanced, parentheses-grouped logic simply as you usually would. For a full breakdown of the right way to use operators, negate options, or disguise stylesheets from older browsers, reference the Logic and Operators part of the @media almanac. It’s also price referencing the part on nesting and complicated decision-making when constructing advanced 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 some other , @custom-media has help for the ranged media question syntax which makes use of operators, e.g. larger than (>), lower than (<), and equals (=), to judge situations:

/* 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 situations:

@custom-media --narrow-window (width < 30rem);
@custom-media --small-and-hover (--narrow-window) and (hover: hover);

@media (--small-and-hover) {
  /* Types for mobile-sized screens with hover capabilities */
}

Nonetheless, if a loop is detected, all concerned {custom} media queries are handled as undefined. As an illustration, if --query-a references --query-b, then --query-b can’t reference --query-a. Equally, a {custom} media question can’t 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 impression in your browser’s developer instruments very troublesome.

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 Present Properties

Normal boilerplate comparable to (prefers-reduced-motion: cut back) can be utilized many instances throughout a codebase, and people bytes add up. You should use @custom-media to outline easier options:

@custom-media --prefers-reduced-motion (prefers-reduced-motion: cut 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 aren’t uncovered to the JavaScript matchMedia() methodology, which means this code will not work, even in case you have the alias outlined someplace in your web page.

matchMedia("(--tablet)")

Specification

The @custom-media at-rule is outlined within the Media Queries Degree 5 specification.

Browser Help

Unsupported browsers largely ignore @custom-media, so fallback declarations and progressive enhancement methods could be advantageous. You should use @helps to verify if @custom-media is supported within the person’s browser, like so:

@helps (at-rule(@custom-media)) {
  /* ... */
}

Paradoxically, nonetheless, at time of writing, the @helps at-rule analysis performance doesn’t have full help throughout browsers (Chrome 148+ solely), so you will have to verify whether it is supported in your case. You possibly can see the dialogue on this in CSS Drafts Challenge #2463.

One other strategy is to make use of a instrument comparable to PostCSS Customized Media, which can develop the principles in a construct step to realize wider browser help.