CSS `@custom-media`

[ramiy]

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-features: custom-media-queries

https://web-platform-dx.github.io/web-features-explorer/features/custom-media-queries/

Test Links

web-platform-tests/wpt#48480

Additional Signals

Browser Bugs:

• Mozilla Bug: https://bugzilla.mozilla.org/show_bug.cgi?id=1744292 (added support behind a flag in Firefox 146)
• Chromium Bug: https://issues.chromium.org/issues/40781325 (promising progress)
• WebKit Bug: https://bugs.webkit.org/show_bug.cgi?id=233820

Interop:

• 2024: Custom Media Queries #421
• 2025: CSS @custom-media at-rule to manage media queries #714

[github-actions]

This comment was automatically generated based on the information you provided. Please don't edit it.

No web features (from the web-features project) were found in your proposal. If your proposal doesn't correspond to a web feature, that is fine.
Otherwise, please update your initial comment to include web-features: <feature-id>.
To find feature IDs, use the web-features explorer.

[ramiy]

web-feature: https://web-platform-dx.github.io/web-features-explorer/features/custom-media-queries/

[yisibl]

Looks like @emilio has implemented @custom-media in Firefox 146, congratulations!

https://bugzilla.mozilla.org/show_bug.cgi?id=1744292#c2