CSS @custom-media #1036
Description
Description
The @custom-media at-rule lets developers define reusable, named aliases for complex or repetitive media queries. Instead of hardcoding breakpoints across multiple stylesheets, custom media queries centralize these definitions in one place, making CSS easier to maintain and ensuring consistent breakpoints across a project.
With @custom-media, updating a breakpoint value is simple - change it once in the declaration, and all references update automatically throughout the codebase. This reduces duplication, streamlines responsive design workflows, and improves long-term maintainability.
Example: Using custom media as aliases across breakpoints
@custom-media --narrow-window (max-width: 32em);
@media (--narrow-window) {
}
@media (--narrow-window) and (hover) {
}
@media (--narrow-window) and (orientation: portrait) {
}Example: Centralizing all breakpoints in one place
@custom-media --mobile (max-width: 480px);
@custom-media --tablet (max-width: 768px);
@custom-media --laptop (max-width: 1024px);
@custom-media --desktop (max-width: 1440px);
@custom-media --widescreen (min-width: 1441px);Specification
https://www.w3.org/TR/mediaqueries-5/#custom-mq
web-feature
web-platform-dx/web-features#3325
Test Links
Additional Signals
Browser Bugs:
- Chromium Bug: https://issues.chromium.org/issues/40781325 (promising progress)
- WebKit Bug: https://bugs.webkit.org/show_bug.cgi?id=233820
- Mozilla Bug: https://bugzilla.mozilla.org/show_bug.cgi?id=1744292
Interop: