Big update!Introducing GitHub Bot Commands. Learn more
Log inBook a demo


Package Overview
File Explorer

Advanced tools


Use Custom Media Queries in CSS


Version published
Weekly downloads
decreased by-10.23%

Weekly downloads



PostCSS Custom Media PostCSS Logo

npm version CSS Standard Status Build Status Discord

PostCSS Custom Media lets you define @custom-media in CSS following the Custom Media Specification.

@custom-media --small-viewport (max-width: 30em); @media (--small-viewport) { /* styles for small viewport */ } /* becomes */ @media (max-width: 30em) { /* styles for small viewport */ }

true and false

With @custom-media you can use the constants true and false. These are especially handy when debugging.

If you are unsure how your page is affected when a certain media query matches or not you can use these, to quickly toggle the results. This plugin downgrades these queries to something that works in all browsers.

Quickly check the result as if the query matches:

@custom-media --small-viewport true; @media (--small-viewport) { /* styles for small viewport */ } /* becomes */ @media (max-color:2147477350) { /* styles for small viewport */ }

Quickly check the result as if the query does not match:

@custom-media --small-viewport false; @media (--small-viewport) { /* styles for small viewport */ } /* becomes */ @media (color:2147477350) { /* styles for small viewport */ }

logical evaluation of complex media queries

It is impossible to accurately and correctly resolve complex @custom-media queries as these depend on the browser the queries will eventually run in.

Some of these queries will have only one possible outcome but we have to account for all possible queries in this plugin.

⚠️ When handling complex media queries you will see that your CSS is doubled for each level of complexity.
GZIP works great to de-dupe this but having a lot of complex media queries will have a performance impact.

An example of a very complex (and artificial) use-case :

@custom-media --a-complex-query tty and (min-width: 300px); @media not screen and ((not (--a-complex-query)) or (color)) { /* Your CSS */ } /* becomes */ @media tty and (min-width: 300px) { @media not screen and ((not (max-color:2147477350)) or (color)) { /* Your CSS */ } } @media not tty and (min-width: 300px) { @media not screen and ((not (color:2147477350)) or (color)) { /* Your CSS */ } }


Add PostCSS Custom Media to your project:

npm install postcss postcss-custom-media --save-dev

Use it as a PostCSS plugin:

const postcss = require('postcss'); const postcssCustomMedia = require('postcss-custom-media'); postcss([ postcssCustomMedia(/* pluginOptions */) ]).process(YOUR_CSS /*, processOptions */);

PostCSS Custom Media runs in all Node environments, with special instructions for:



The preserve option determines whether the original notation is preserved. By default, it is not preserved.

postcssCustomMedia({ preserve: true }) @custom-media --small-viewport (max-width: 30em); @media (--small-viewport) { /* styles for small viewport */ } /* becomes */ @custom-media --small-viewport (max-width: 30em); @media (max-width: 30em) { /* styles for small viewport */ } @media (--small-viewport) { /* styles for small viewport */ }



What is postcss-custom-media?

Use Custom Media Queries in CSS

Is postcss-custom-media popular?

The npm package postcss-custom-media receives a total of 6,703,130 weekly downloads. As such, postcss-custom-media popularity was classified as popular.

Is postcss-custom-media well maintained?

We found that postcss-custom-media demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.It has 4 open source maintainers collaborating on the project.

Last updated on 19 Nov 2022

Did you know?

Socket installs a Github app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install Socket


Subscribe to our newsletter

Get open source security insights delivered straight into your inbox. Be the first to learn about new features and product updates.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc