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

[wpt-interop]

Thank you for proposing CSS @custom-media for Interop 2026.

We want to let you know it was not selected to be part of Interop this year.

On behalf of the entire Interop team, thank you for submitting it 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.

Posted on behalf of the Interop team.