What is @custom-media and why do you need it?
Go back
2 min read

What is @custom-media and why do you need it?

The @custom-media rule from CSS Media Queries Level 5 lets you define reusable named aliases for complex media conditions right in CSS.

What is @custom-media and why do you need it?

In modern CSS, media queries can get long and visually noisy, especially when you combine checks like (min-width: 1024px) and (hover: hover) and (pointer: fine).

The CSS Media Queries Level 5 specification introduces the @custom-media rule. It lets you declare global named aliases for complex media conditions directly in CSS, much like custom properties (var()).

/* Declare a named media query */
@custom-media --desktop (min-width: 1024px);
@custom-media --hoverable (hover: hover) and (pointer: fine);

/* Use it in your styles */
@media (--desktop) and (--hoverable) {
  .card:hover {
    transform: translateY(-4px);
  }
}

Main benefits:

  1. DRY in CSS: Breakpoints and capability checks are not duplicated hundreds of times across stylesheets.
  2. Single source of truth: When a breakpoint changes, you update it in one place.
  3. Semantics: Instead of magic numbers like 768px, your code reads as clear conditions: --desktop, --touch, --retina.

More examples:

/* Breakpoints */
@custom-media --from-360 (min-width: 360px);
@custom-media --from-760 (min-width: 760px);
@custom-media --from-1260 (min-width: 1260px);

/* Wide color gamut */
@custom-media --true-hdr (color-gamut: p3) and (dynamic-range: high);

@media (--true-hdr) {
  .hero-banner {
    background-color: color(display-p3 1 0 0); /* Vivid ultra-red */
  }
}

/* Themes & A11y */
@custom-media --dark-mode (prefers-color-scheme: dark);
@custom-media --reduce-motion (prefers-reduced-motion: reduce);

@media (--reduce-motion) {
  * {
    animation-duration: 0.001ms !important;
  }
}

🚦 What about browser support?

Right now, @custom-media is natively implemented only in Firefox behind an experimental flag (layout.css.custom-media.enabled). Chromium and WebKit still have the feature under discussion or in development.

How to use it in production today:

  1. PostCSS / LightningCSS: Plugins such as postcss-custom-media compile aliases down to standard @media (...) queries at build time.
  2. Container Style Queries: Use @container style() if you want similar logic in native CSS without a build step.
/* Definition */
:root {
  @media (hover: hover) and (pointer: fine) {
    --mouse: any-valid-ident;
  }

  @media (hover: none) and (pointer: coarse) {
    --touch: true;
  }
}

/* Usage */
@container style(--mouse) {
  /* ... */
}
@container style(--touch) {
  /* ... */
}

Read the original article

Подписывайтесь на мой Telegram-канал

Copied