https://github.com/csstools/js-custom-media
Use Custom Media Queries in JS
https://github.com/csstools/js-custom-media
Last synced: 11 months ago
JSON representation
Use Custom Media Queries in JS
- Host: GitHub
- URL: https://github.com/csstools/js-custom-media
- Owner: csstools
- License: cc0-1.0
- Created: 2018-10-08T14:23:03.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2019-05-13T11:52:06.000Z (almost 7 years ago)
- Last Synced: 2024-05-21T18:31:59.320Z (almost 2 years ago)
- Language: JavaScript
- Homepage: https://csstools.github.io/js-custom-media
- Size: 9.77 KB
- Stars: 9
- Watchers: 7
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# JS Custom Media [
][JS Custom Media]
[![NPM Version][npm-img]][npm-url]
[![Build Status][cli-img]][cli-url]
[![Support Chat][git-img]][git-url]
[JS Custom Media] lets you use Custom Media Queries in JS, following the
[CSS Media Queries] specification.
```bash
npm install js-custom-media
```
## Usage
```js
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.
```js
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.
```js
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`.
```js
import { customMedia } from 'js-custom-media';
customMedia.set('--md', '(min-width: 640px)');
```
#### get
The `get` method returns the value of a custom media query.
```js
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](#custommedia) and [polyfillMatchMedia](#polyfillmatchmedia).
This can only be used for non-standard behavior, such as
[Usage with PostCSS Custom Media](#usage-with-postcss-custom-media).
```js
import { extensions } from 'js-custom-media';
extensions['--some-mq'] = '(width >= 960px)'; // add custom media queries in a non-standard way
```
[cli-img]: https://img.shields.io/travis/csstools/js-custom-media.svg
[cli-url]: https://travis-ci.org/csstools/js-custom-media
[git-img]: https://img.shields.io/badge/support-chat-blue.svg
[git-url]: https://gitter.im/postcss/postcss
[npm-img]: https://img.shields.io/npm/v/js-custom-media.svg
[npm-url]: https://www.npmjs.com/package/js-custom-media
[CSS Media Queries]: https://drafts.csswg.org/mediaqueries-5/#custom-mq
[JS Custom Media]: https://github.com/csstools/js-custom-media
[PostCSS Custom Media]: https://github.com/postcss/postcss-custom-media/