Custom Media Queries: @custom-media in PostCSS vs. Native CSS

1. The core problem: the same width value in twenty places

In a stylesheet that has grown over time, a breakpoint like min-width: 48rem often shows up in dozens of places, scattered across different component files. If the breakpoint changes because the design team adjusts the tablet boundary, that number has to be found and replaced manually at every single location, with the risk of missing one spot and producing an inconsistent result.

Custom media queries solve exactly this problem by defining a condition like --breakpoint-tablet exactly once and then referencing it by name. That is conceptually the same thing custom properties do for color values or spacing, just applied at the level of entire media query conditions instead of single values.

2. @custom-media in PostCSS: syntax and basic setup

With the PostCSS plugin postcss-custom-media, a named condition is declared with the @custom-media at-rule, typically in a central file loaded before every other stylesheet. The name always starts with two dashes, just like custom properties, and can then be used as a condition in any @media rule across the project.

During the build step, PostCSS replaces every use of @media (--breakpoint-tablet) with the actual, spelled-out condition, so the shipped CSS ends up containing perfectly ordinary media queries every browser understands. In the source code, the development team still gets the descriptive name, which meaningfully improves readability and maintainability.

/* breakpoints.css -- defined centrally, loaded before every other file */
@custom-media --breakpoint-tablet (min-width: 48rem);
@custom-media --breakpoint-desktop (min-width: 64rem);
@custom-media --dark-mode (prefers-color-scheme: dark);

/* component.css -- used in as many places as needed */
.sidebar {
  display: none;
}

@media (--breakpoint-tablet) {
  .sidebar {
    display: block;
  }
}

3. Combining conditions: and, or and nested custom media queries

A particular advantage of @custom-media is that several named conditions can be combined with and or or without writing out the underlying definitions twice. A condition like tablet or larger, but not in dark mode can be expressed readably that way, instead of maintaining one long, hard-to-parse media query chain.

PostCSS also allows using one custom media query inside the definition of another, enabling hierarchical conditions like desktop, which includes tablet. That nesting should be used sparingly, though, because it quickly becomes confusing once a condition is composed of other conditions across several levels.

@custom-media --breakpoint-tablet (min-width: 48rem);
@custom-media --dark-mode (prefers-color-scheme: dark);

@media (--breakpoint-tablet) and not (--dark-mode) {
  .banner {
    background: #ede9fe;
  }
}

@media (--breakpoint-tablet) or (--dark-mode) {
  .contrast-note {
    display: block;
  }
}

4. The native path: custom media queries in Media Queries Level 5

The Media Queries Level 5 specification defines the same @custom-media at-rule natively for the browser, with syntax nearly identical to PostCSS. Once a browser supports that rule, no build-time translation is needed anymore, because the browser resolves the condition itself at runtime and applies the stored definition directly on every use of @media (--breakpoint-tablet).

The practical difference to the PostCSS variant lies mainly in the fact that native custom media queries could eventually be influenced by JavaScript or CSS custom properties as the specification is extended, while a PostCSS condition is fixed as a build-time constant and can no longer change at runtime in the browser.

5. Browser support today and a realistic timeline

As things stand, no current browser fully supports the native @custom-media rule in a production-ready way; it sits at various experimental stages behind flags or in early implementations. A production project therefore cannot rely on native support alone, and still needs PostCSS or a comparable build-time solution to make custom media queries usable today.

For project planning, that means: teams working with postcss-custom-media today are already using exactly the syntax that will later work natively, because both specifications are deliberately aligned. That significantly minimizes migration risk, since no syntax change will be required, only the build step can eventually be dropped.

6. Migration strategy: from the PostCSS plugin to the native browser feature

The recommended approach is bundling all custom media definitions in a single, central file from the start, instead of spreading them across the entire project. That turns the later migration into a one-file change: once native support exists in every relevant target browser, the PostCSS plugin is simply removed from the build pipeline, without changing the definitions themselves.

It is also important to avoid @supports checks during this transition period, since @custom-media in the PostCSS case fully resolves into regular @media rules before the code ever reaches the browser. The feature test only becomes relevant once a mixed codebase of native and not-yet-translated syntax is actually in use, which a well-planned migration should generally avoid.

# Before: PostCSS handles the resolution at build time
npm install postcss-custom-media --save-dev

# postcss.config.js
module.exports = {
  plugins: [
    require('postcss-custom-media'),
    require('autoprefixer'),
  ],
};

# After, once native support is sufficient:
# just remove the plugin line from postcss.config.js,
# the @custom-media definitions stay unchanged.

7. Custom media queries alongside Tailwind CSS: a sensible addition, not a replacement

In a project using Tailwind CSS, the built-in breakpoint prefixes like md: or lg: already cover most of the use case, because they pursue exactly the same goal: named, consistently reusable conditions instead of spelled-out width values. Custom media queries become relevant where conditions go beyond plain breakpoints, for example a combination of prefers-reduced-motion and a minimum width that deserves its own, reusable name.

Even in hand-written CSS outside the utility framework, for example complex component libraries or design system base stylesheets, @custom-media remains the right tool for naming conditions just as consistently as color and spacing values are named through custom properties.

8. Naming conventions: semantic names instead of raw pixel values

A common beginner mistake is naming custom media queries after their numeric value, for example --bp-768, instead of after their actual meaning in the design system. If the underlying width value later changes because the design team shifts the tablet breakpoint from 48rem to 50rem, the name --bp-768 suddenly becomes semantically wrong, even though it stays unchanged in the code and thereby causes confusion.

A semantic naming style based on purpose rather than value has proven itself instead, for example --breakpoint-tablet or --breakpoint-nav-collapse, which stays correct even when the actual number behind it changes. The same convention applies to functional conditions like --dark-mode or --reduced-motion, which describe the purpose of the condition instead of repeating the underlying media feature syntax in the name.

/* Not ideal: the name is coupled to a specific numeric value */
@custom-media --bp-768 (min-width: 48rem);

/* Better: the name describes the purpose, stays correct if the value changes */
@custom-media --breakpoint-tablet (min-width: 48rem);
@custom-media --breakpoint-nav-collapse (max-width: 61.9375rem);
@custom-media --reduced-motion (prefers-reduced-motion: reduce);

9. PostCSS approach and native standard side by side

Both paths lead to the same result syntactically, but differ in when resolution happens, how browser-dependent they are, and the practical consequences that follow for the build pipeline and debugging.

10. Summary

11. FAQ: Custom Media Queries: The Essentials at a Glance