README
JS Custom Media
JS Custom Media lets you use Custom Media Queries in JS, following the CSS Media Queries specification.
npm install js-custom-media
Usage
import { customMedia, polyfillMatchMedia } from 'js-custom-media';
// define a custom media query
customMedia.set('--md', '(width > 640px)');
// polyfill `window.matchMedia`
const matchMedia = polyfillMatchMedia(window.matchMedia);
// match a custom media query
mq = matchMedia('(--md)');
mq.addListener(update);
// apply the custom media query
function update() {
// do something with `mq.matches`
}
update();
A typical implementation of this script is about 576 bytes minified and gzipped.
Usage with PostCSS Custom Media
PostCSS Custom Media lets you import Custom Media from external files. These files can be used by this library as well.
import { extensions, polyfillMatchMedia } from 'js-custom-media';
// get variables that include `'custom-media'` (or `customMedia`)
import variables from 'path/to/variables.json';
// add variables’ custom media to `extensions`
Object.assign(extensions, variables['custom-media']);
// get built-in support for variables’ custom media
window.matchMedia = polyfillMatchMedia(window.matchMedia);
Features
polyfillMatchMedia
The polyfillMatchMedia
method returns a wrapped version of matchMedia
that
can parse custom media queries.
import { polyfillMatchMedia } from 'js-custom-media';
const matchMedia = polyfillMatchMedia(window.matchMedia); // works like window.matchMedia
customMedia
The customMedia
object includes 2 methods for getting and setting custom
media queries.
set
The set
method adds a custom media query that is readable by the wrapped
version of matchMedia
.
import { customMedia } from 'js-custom-media';
customMedia.set('--md', '(min-width: 640px)');
get
The get
method returns the value of a custom media query.
import { customMedia } from 'js-custom-media';
CSS.customMedia.get('--md'); // (min-width: 640px)
extensions
The extensions
object is the internal map of custom media queries used by
customMedia and polyfillMatchMedia.
This can only be used for non-standard behavior, such as Usage with PostCSS Custom Media.
import { extensions } from 'js-custom-media';
extensions['--some-mq'] = '(width >= 960px)'; // add custom media queries in a non-standard way