Limited support Useful when Custom media queries helps adapt the interface to user preferences, display capability, or environment conditions.

Custom media queries

Experimental: This is an experimental technology

Check the Browser compatibility table carefully before using this in production.

The @custom-media CSS at-rule defines aliases for long or complex media queries. Instead of repeating the same hardcoded <media-query-list> in multiple @media at-rules, it can be defined once in a @custom-media at-rule and referenced throughout the stylesheet whenever needed.

Media queries

Browser support

Feature Desktop Mobile
Chrome
Edge
Firefox
Safari
Chrome Android
Safari iOS
@custom-media
Experimental
148
DOM API
CSSCustomMediaRule
Experimental
146
1+Supported (version) Not supported ※Has note Sub-feature descriptions sourced from MDN Web Docs (CC BY-SA 2.5)
Notes 1 item(s)
Experimental
  • Requires an experimental browser flag to be enabled
Notes 1 item(s)
Experimental
  • Requires an experimental browser flag to be enabled

Syntax

CSS 
@custom-media --narrow-window (max-width: 30em);
@custom-media --wide-window (min-width: 60em);

@media (--narrow-window) {
  .container { padding: 1rem; }
}

Live demo

@custom-media definition

CSS @custom-media definition demo.

PreviewFullscreen

usageexample

CSS usageexample demo.

PreviewFullscreen

Multipledefinition

CSS Multipledefinition demo.

PreviewFullscreen

Use cases

  • Adaptive styling

    Use Custom media queries to tailor layout or presentation to device features and user settings.

  • Progressive enhancement

    Keep the default experience solid, then layer in device-specific or preference-aware improvements.

Cautions

  • Do not rely on a media condition as the only path to essential functionality.
  • Document the breakpoint or environment strategy so conditions stay consistent across the codebase.

Accessibility

  • Media-query adaptations should preserve keyboard access, reading order, and touch usability.
  • Preference-aware styling should enhance accessibility rather than replace baseline accessible defaults.

Related links