@custom-media
Media queries are one of the most repeated pieces of CSS in any project. A breakpoint like (min-width: 48em) might appear dozens of times across your stylesheets, and if you ever need to change it, you have to find and update every instance. The @custom-media at-rule solves this by letting you define a named alias for a media query and reference that name everywhere instead.
There is a catch: as of now, no browser ships @custom-media in a stable release. Firefox has it behind a flag, and Chrome and Safari have not implemented it yet. That means you need a build tool to use it today. Both PostCSS and Lightning CSS can compile @custom-media into standard media queries that every browser understands. This is a real-world example of how build tools unlock CSS features before browsers catch up.
The Problem: Repeated Magic Numbers
Consider a typical stylesheet with several responsive breakpoints. The same values appear in file after file:
/* layout/primary.css */
@media (min-width: 48em) {
.site-grid {
grid-template-columns: 1fr 3fr;
}
}
/* components/card.css */
@media (min-width: 48em) {
.cards {
grid-template-columns: repeat(2, 1fr);
}
}
/* components/nav.css */
@media (min-width: 64em) {
.site-nav {
flex-direction: row;
}
}
The value 48em is a magic number. Nothing in the code explains what it represents. Is it the tablet breakpoint? The point where the sidebar appears? If you need to adjust it, you have to search across every file and hope you do not miss one. Custom properties (var()) cannot help here because CSS does not allow custom properties inside media query conditions. That is the gap @custom-media fills.
The Syntax
A @custom-media rule defines a named alias for a media query. The name must start with two hyphens, just like a custom property:
@custom-media --medium (min-width: 48em);
@custom-media --large (min-width: 64em);
@custom-media --motion (prefers-reduced-motion: no-preference);
Once defined, you reference the name inside a standard @media rule:
@media (--medium) {
.cards {
grid-template-columns: repeat(2, 1fr);
}
}
@media (--large) {
.site-nav {
flex-direction: row;
}
}
@media (--motion) {
.hero {
animation: fade-in 0.4s ease;
}
}
The benefits are immediate. The breakpoint value lives in one place. Every file that uses (--medium) is guaranteed to reference the same width. If the design changes and the tablet breakpoint moves from 48em to 50em, you update one line and rebuild. You also gain readability: @media (--medium) communicates intent in a way that @media (min-width: 48em) does not.
Where to Define Them
In the layered architecture you set up in the CSS Architecture reading, @custom-media definitions belong in the tokens/ directory. They are design tokens, just like your color and spacing variables. You could add them to tokens/variables.css or create a dedicated tokens/breakpoints.css file. Either approach works. The important thing is that they live alongside your other tokens so anyone looking for a design value knows where to find it.
/* tokens/breakpoints.css */
@custom-media --small (min-width: 30em);
@custom-media --medium (min-width: 48em);
@custom-media --large (min-width: 64em);
@custom-media --x-large (min-width: 80em);
@custom-media --motion (prefers-reduced-motion: no-preference);
@custom-media --dark (prefers-color-scheme: dark);
Notice that @custom-media is not limited to width breakpoints. Any valid media query can be aliased, including preference queries like prefers-reduced-motion and prefers-color-scheme. This is especially useful for accessibility and theming conditions that tend to be long and easy to mistype.
Making It Work in Browsers
You have seen the syntax and know where to put the definitions, but if you add @custom-media to your CSS and open the page in a browser right now, nothing will happen. The browser does not recognize @media (--medium) and will silently ignore it. This is where your build tool earns its keep.
When a feature exists in a specification but browsers have not implemented it yet, developers bridge the gap with what is called a polyfill. A polyfill is any tool or piece of code that provides a feature the environment does not yet support natively. In JavaScript, polyfills are usually small scripts that add missing browser functions at runtime. In CSS, the polyfill happens at build time instead: the build tool reads the modern syntax you wrote, replaces it with equivalent standard CSS, and outputs a file the browser already knows how to handle. You get the authoring benefits of the new feature today, and the browser never sees anything it cannot understand.
Both tools covered in this unit can polyfill @custom-media. The setup depends on which one you chose.
PostCSS
If you chose the PostCSS path, install the postcss-custom-media plugin:
Then add it to your postcss.config.js. It should come after postcss-import (so imports are resolved first) and before cssnano (so the expanded output gets minified):
module.exports = {
plugins: [
require('postcss-import'),
require('postcss-custom-media'),
require('autoprefixer'),
require('cssnano')({ preset: 'default' })
]
};
Lightning CSS
If you chose the Lightning CSS path, you do not need to install anything extra. Lightning CSS understands @custom-media natively and compiles it during bundling. Your existing build command already handles it. Just write the definitions, run your build, and the output will contain standard media queries.
Before and After
Here is what the polyfill produces. Your source files stay clean and readable, while the output contains only standard CSS that every browser understands.
Source (What You Write)
/* tokens/breakpoints.css */
@custom-media --medium (min-width: 48em);
/* components/card.css */
@media (--medium) {
.cards {
grid-template-columns: repeat(2, 1fr);
}
}
Output (What the Browser Receives)
@media (min-width: 48em) {
.cards {
grid-template-columns: repeat(2, 1fr);
}
}
The @custom-media definition is gone. The named reference (--medium) has been replaced with the actual query (min-width: 48em). The browser sees nothing unusual.
A Practical Refactor
To see the real value, try this exercise with your portfolio or the CSS Bundling starter files. Take any stylesheet that contains repeated media queries and refactor it:
-
Create a
tokens/breakpoints.cssfile with your@custom-mediadefinitions. -
Add an
@importfor it inmain.cssinside the tokens layer group (before any file that uses the breakpoints). - Replace every hard-coded media query value with the named alias.
- Run your build and verify that the output contains the expanded queries and the page looks the same.
Then change one of the breakpoint values in breakpoints.css, rebuild, and confirm that every component picks up the change. That one-line edit updating the entire project is the developer experience improvement that @custom-media provides.
Beyond Breakpoints
Named media queries are most commonly used for viewport breakpoints, but they shine anywhere a media condition is repeated or complex. Some useful patterns:
/* Accessibility */
@custom-media --motion (prefers-reduced-motion: no-preference);
@custom-media --high-contrast (prefers-contrast: more);
/* Theming */
@custom-media --dark (prefers-color-scheme: dark);
/* Input type */
@custom-media --touch (pointer: coarse);
@custom-media --mouse (hover: hover) and (pointer: fine);
/* Orientation */
@custom-media --landscape (orientation: landscape);
A query like (hover: hover) and (pointer: fine) is easy to get wrong from memory. Naming it --mouse makes the intent clear and eliminates the chance of a typo. Adam Argyle's Open Props project includes over 45 predefined custom media aliases if you want inspiration for naming conventions.
Browser Support Outlook
The @custom-media specification is part of the Media Queries Level 5 draft. Firefox has an implementation behind a flag (layout.css.custom-media.enabled), but Chrome and Safari have not shipped it yet. You can track the current status on Can I Use.
This is worth understanding as a broader lesson. Some CSS features are stable in the specification and useful in practice but still waiting on browser implementations. Polyfills let you use those features now by compiling them into compatible output at build time. When browsers eventually ship native support, you remove the polyfill step and your source code stays exactly the same. The feature works today, and it only gets simpler over time.
Resources
- MDN: @custom-media – syntax reference and examples
- Media Queries Level 5 Specification – the formal definition
- postcss-custom-media – the PostCSS polyfill plugin
-
Lightning CSS – handles
@custom-medianatively during bundling - Open Props Custom Media – a library of predefined media aliases for inspiration
- Can I Use: @custom-media – current browser support
Teaching Video Checklist
Your teammates should come away from your video understanding these concepts:
-
The problem
@custom-mediasolves: repeated magic numbers in media queries that are hard to update and easy to mistype -
The syntax: how to define a named alias and reference it inside
@mediarules -
Where definitions belong in the project architecture (the
tokens/directory) - What a polyfill is and how the build tool compiles named queries into standard media queries, with a before and after comparison of the output
- A live refactor: replacing hard-coded breakpoints with named aliases, changing the value in one place, and showing the change propagate across the entire build