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