CSS `@custom-media` at-rule to manage media queries

[ramiy]

Description

The Media Queries Level 5 specification introduces the @custom-media at-rule, which acts as an alias for complex and repetitive media queries. Instead of hardcoding media query breakpoints across multiple CSS files, developers can declare breakpoint values using @custom-media rules. These custom media queries can then be reused, streamlining CSS management and improving maintainability.

With @custom-media, developers can centralize all breakpoint definitions in one place, ensuring consistency across stylesheets. When a breakpoint value needs to change, only the @custom-media declaration must be updated, and all instances across CSS files are automatically adjusted.

Use them as aliases in multiple breakpoints:

@custom-media --narrow-window (max-width: 32em);

@media (--narrow-window) {
}

@media (--narrow-window) and (hover) {
}

@media (--narrow-window) and (orientation: portrait) {
}

Use them for grouping all your breakpoints in one place:

@custom-media --mobile-screen (max-width: 480px);
@custom-media --tablet-screen (max-width: 768px);
@custom-media --laptop-screen (max-width: 1024px);
@custom-media --desktop-screen (max-width: 1440px);
@custom-media --widescreen (min-width: 1441px);

I was hoping my MDN PRs will be merged before Interop 2025, but as it was not merged yet, check the following PRs for more information and code examples:

• MDN: Add CSS @custom-media at-rule mdn/content#35755
• BCD: feat(css): Add browser compatibility data for the CSS @custom-media at-rule mdn/browser-compat-data#24338

Specification

• Spec: https://www.w3.org/TR/mediaqueries-5/
• Definition: https://www.w3.org/TR/mediaqueries-5/#custom-mq

Browser Bugs

• Chromium Bug: https://issues.chromium.org/issues/40781325
• WebKit Bug: https://bugs.webkit.org/show_bug.cgi?id=233820
• Mozilla Bug: https://bugzilla.mozilla.org/show_bug.cgi?id=1744292

Additional Signals

Real-World Application: Elementor Case Study

I currently work at Elementor, a popular WordPress page builder powering over 25% of all WordPress websites and ~11% of all websites globally.

We continuously strive to optimize our CSS for millions of websites. Currently, when our users update breakpoint sizes, we need to re-generate multiple CSS files.. With @custom-media support across all browsers, we will be able to simplify this by redefining new breakpoint size in a single line of code. This eliminates the need for full CSS regeneration because only the last declared @custom-media rule is applied when multiple rules share the same name.

The Way Forward

Just as Custom CSS Properties revolutionized styling by enabling dynamic values, Custom Media Queries will significantly enhance how developers handle responsive design. By enabling media query reusability and eliminating redundancy, @custom-media is poised to be a game changer in the future of CSS development.

[gsnedders]

There don't appear to be any tests in WPT for @custom-media.

[adamstddrd]

Worth noting that web developers are already using custom media queries en masse, they're just doing it through pre/post processors like SASS, PostCSS, and Lightning CSS. The custom media plugin for PostCSS that replicates the behavior of this spec has 5.7 million weekly downloads on NPM. Implementing would go a long way towards making tools like these optional instead of a mandatory means for writing maintainable CSS.

[romainmenke]

The custom media plugin for PostCSS that replicates the behavior of this spec has 5.7 million weekly downloads on NPM

It is also the second most viewed readme in our monorepo (after nesting with two other links being the main page and postcss-preset-env).
This typically is a good indicator for which specific PostCSS plugins CSS authors care about most.

• npm downloads are inflated because this feature is included in the postcss-preset-env bundle and we can't know how many of those actually use it.
• the absolute view numbers might seem low but people rarely read docs for projects like these.

[romainmenke]

I've added a patch with some tests for WPT: web-platform-tests/wpt#48480

[ai36]

Outrageous! Instead of creating new syntax, just restrict the use of CSS variables at the @rules level.

[romainmenke]

@gsnedders Is there anything missing or that could be improved about this proposal?

[mayank99]

I'll repeat what I said last time, which is that this feature can be (partially) emulated by style queries (#828).

@media (width <= 40em) {
  :root { --screen: mobile; }
}
@media (width <= 70em) {
  :root { --screen: desktop; }
}

@container style(--screen: mobile) {
  /* styles */
}

@container style(--screen: desktop) {
  /* styles */
}

That's not to say we shouldn't pursue @custom-media (clearly this is something developers want). I'm only mentioning it as a potential reason for prioritizing container style queries.

[romainmenke]

@mayank99 I don't think it can really emulate this.
Container queries for example can't be used on @import or in html for image sizes.

I also don't think it can be an equivalent tool for writing and maintaining CSS.
Such indirection wouldn't help with proper code editor support.

You would want autocomplete, hover tooltips, ...

[mayank99]

@romainmenke I totally agree we should have all of these things. That's why I said "partially emulate" and included another clarification note at the end. It's not a proper replacement.

[wpt-interop]

Thank you for proposing CSS @custom-media at-rule to manage media queries for inclusion in Interop 2025.

We wanted to let you know that this proposal was not selected to be part of Interop this year.

On behalf of the entire Interop team, thank you for submitting this proposal for consideration. We got many more proposals than we could include in this year's project, necessitating some difficult choices. Please note this should not be taken as a comment on the technology as a whole, or our willingness to consider it for Interop in the future. We appreciate the work you put into your proposal, and would welcome your participation in future rounds of Interop.

For an overview of our process, see proposal selection. Thank you again for contributing to Interop 2025.

Posted on behalf of the Interop team.