css-mediaquery

What is css-mediaquery?

The css-mediaquery package is a tool for parsing and evaluating CSS media queries. It is useful for determining if a media query matches a given set of values or for extracting information from media query strings. This can be particularly helpful for server-side rendering, where you might want to match styles to a device's characteristics, or for dynamically adjusting UI components in JavaScript based on media query logic.

What are css-mediaquery's main functionalities?

Parsing media queries

This feature allows you to parse a CSS media query string into a structured format that can be easily manipulated or evaluated in JavaScript.

const cssMediaQuery = require('css-mediaquery');
const parsedQuery = cssMediaQuery.parse('screen and (min-width: 480px)');
console.log(parsedQuery);

Evaluating media queries

This feature enables you to evaluate whether a media query matches a given set of values, such as the type of device or the viewport width. This is useful for conditionally applying styles or functionality.

const cssMediaQuery = require('css-mediaquery');
const matches = cssMediaQuery.match('screen and (min-width: 480px)', {
  type: 'screen',
  width: '1024px'
});
console.log(matches); // true or false

Other packages similar to css-mediaquery

enquire.js

Enquire.js is a lightweight, pure JavaScript library for responding to CSS media queries. It is similar to css-mediaquery but is more focused on providing a JavaScript API for responding to media queries in the browser, rather than parsing or evaluating them in a general context.

matchmediaquery

This package is similar to css-mediaquery in that it allows you to evaluate media queries in JavaScript. However, matchmediaquery is designed to mimic the window.matchMedia API found in browsers, providing a polyfill for environments where matchMedia is not available.

json2mq

json2mq is a package that allows you to generate media query strings from JavaScript objects. While it does not evaluate or parse media queries like css-mediaquery, it provides a complementary functionality that can be useful when constructing media queries dynamically.

README

CSS Media Query

Parses and determines if a given CSS Media Query matches a set of values via JavaScript.

Installation

Install via npm:

$ npm install css-mediaquery

Usage

This package has two exports: parse(), and match() which can parse CSS Media Queries and determine if a media query matches a given set of values.

Matching

The match() method lets you compare a media query expression with a JavaScript object and determine if a media query matches a given set of values.

var mediaQuery = require('css-mediaquery');

var isMatch = mediaQuery.match('screen and (min-width: 40em)', {
    type : 'screen',
    width: '1024px'
});

console.log(isMatch); // => true

The values specified to check a media query string against should be thought of as if they are the current state of a device/browser. A type value must be specified, and it can not be "all".

Parsing

Existing CSS Parsers don't do a great job at parsing the details of media queries. That's where css-mediaquery shines. You can parse a media query expression and get an AST back by using the parse() method.

var mediaQuery = require('css-mediaquery'),
    ast        = mediaQuery.parse('screen and (min-width: 48em)');

The ast variable will have the following payload:

[
    {
        inverse: false,
        type   : 'screen',

        expressions: [
            {
                modifier: 'min',
                feature : 'width',
                value   : '48em'
            }
        ]
    }
]

This package was written with care to following the W3C Recommendations for CSS3 Media Queries and CSS3 Values and Units. It supports all of the Media Features and will properly convert values to a common unit before comparing them.

License

This software is free to use under the Yahoo! Inc. BSD license. See the LICENSE file for license text and copyright information.