media-query-parser

`media-query-parser`

Create a JS object from a CSS media queries
Create a CSS media query from a JS object
Returns a ParserError for invalid CSS media queries
Spec-compliant - https://www.w3.org/TR/mediaqueries-5/
- All valid queries parsed
  e.g. (100px < width < 200px)
Zero-dependencies
Well tested - every single line
TypeScript friendly

Why?

Other CSS parsers (e.g. css-tree and postcss) do not support all media query syntax out of the box.

Further, the only other media query parser that I'm aware of is postcss-media-query-parser - which is specific to postcss and doesn't parse newer syntax like range expressions (i.e. (width >= 768px)).

This package is a spec-compliant media query parser that can be used in Node/Deno/etc, or on the client that precisely matches the spec right down to the quirks.

These are valid media queries that this library supports:

@media (768px <= width < 1200px);
@media only print and (color);
@media not (not (not (((hover) or ((not (color)))))));
@media (🐈: 😸 /* if cat happy */) {
  /* this query has valid syntax, but is clearly not a real feature 😿 */
  /* For extensions to this project, check out "Libraries that use this" at the bottom of this README */
}

These are invalid media queries that this library will detect:

@media (color) or (hover); /* or cannot be at top level */
@media (min-width: calc(50vw + 10px)); /* functions aren't valid values */
@media not((color)); /* whitespace must follow `not` */
@media (768px < = width < 1200px); /* cannot have a space between `<` and `=` */

Install

This package is available from the npm registry.

npm install media-query-parser

Usage

Supports JavaScript + TypeScript:

import { parseMediaQuery } from "media-query-parser";

const mediaQuery = parseMediaQuery("screen and (min-width: 768px)");
if (!isParserError(mediaQuery)) {
  console.log(mediaQuery);
  // {
  //   _t: "query",
  //   type: "screen",
  //   condition: {
  //     _t: "condition",
  //     op: "and",
  //     nodes: [
  //       {
  //         _t: "in-parens",
  //         node: {
  //           _t: "feature",
  //           context: "value",
  //           feature: "min-width",
  //           value: {
  //             _t: "dimension",
  //             value: 768,
  //             unit: "px",
  //           },
  //         },
  //       },
  //     ],
  //   },
  // }
  // // start/end omitted for brevity

  console.log(stringify(mediaQuery.condition));
  // "(min-width: 768px)"
}

Can also be imported via require("media-query-parser").

v3 (Current) Docs

v2 API docs

Libraries that use this

(See GitHub for dynamically updated list)

Node versions

This source code of this library supports node >=6.5.0 via require() and node >=16.0.0 || ^14.13.1 via import. (Below v6.5.0 is possible but you'd need to transpile the CommonJS code from ES6 yourself)

Contributing

PRs welcome and accepted, simply fork and create
Issues also very welcome
Treat others with common courtesy and respect 🤝

Dev environment (for contributing) requires:

node >= 16.14.0
npm >= 6.8.0
git >= 2.11

Licence

MIT