media-query-parser

media-query-parser

This package's v3 (currently in beta) involves a complete overhaul from v2 to a more sustainable shape. See v2 API docs instead

• 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

This repo/package contains only the parser, stringify and isParserError.

media-query-fns uses this library internally to achieve common use-cases.

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.
     (see `media-query-fns` for feature checking) */
}

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)); /* operators need whitespace */
@media (768px < = width < 1200px); /* cannot have a space between `<` and `=` */

Install

This package is available from the npm registry.

npm install media-query-parser

The shape of Errors are

Usage

Supports JavaScript + TypeScript:

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

const mediaQuery = parseMediaQuery("screen and (min-width: 768px)");
if (!isParserError(mediaQuery)) {
  console.log(mediaQuery);
  // {
  //   type: "query",
  //   mediaType: "screen",
  //   mediaCondition: {
  //     type: "condition",
  //     children: [{
  //       type: "feature",
  //       context: "value",
  //       prefix: "min",
  //       feature: "width",
  //       value: {
  //         type: "dimension", value: 768, unit: "px", flag: "number"
  //       },
  //     }],
  //   },
  // }
  console.log(stringify(mediaQuery.mediaCondition.children[0]));
  // "(min-width: 768px)"
}

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

Full Docs

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