css-media-query-match-kit

Parse and match small CSS media query lists with structured diagnostics.

css-media-query-match-kit is a clean-room TypeScript utility for tools that need to preview or test responsive rules without calling window.matchMedia. The core is framework-agnostic, browser-friendly, ESM-only, and has no runtime dependencies.

Demo

Try the interactive demo: https://packages.wasta-wocket.fr/css-media-query-match-kit/

Install

npm install css-media-query-match-kit

Quick Start

import { matchMediaQueryList } from "css-media-query-match-kit";

const result = matchMediaQueryList(
  "screen and (min-width: 768px) and (orientation: landscape)",
  { type: "screen", width: 1280, height: 720 }
);

console.log(result.matches); // true

Invalid input returns diagnostics instead of throwing:

import { parseMediaQueryList } from "css-media-query-match-kit";

const result = parseMediaQueryList("screen and (min-width: 48em)");

console.log(result.ok); // false
console.log(result.diagnostics[0]?.code); // "invalid-length"

Supported Scope

This package intentionally targets a small, inspectable subset:

• media types: all, screen, print, speech;
• query lists separated by commas;
• not and only modifiers;
• and-joined feature conditions;
• min- and max- comparisons;
• features: width, height, orientation, aspect-ratio, resolution, hover, pointer, color, monochrome;
• units: px, dppx, dpi, and integer ratios such as 16/9.

It does not try to replace a full CSS parser. Modern range syntax such as (width >= 768px), relative units such as em or rem, nested boolean groups, and preference features such as prefers-color-scheme are intentionally outside this first stable scope. Unsupported features are reported as diagnostics so caller UIs can explain what was skipped.

API

parseMediaQueryList(input, options?)

Parses a media query list and returns { ok, input, queries, diagnostics }.

const parsed = parseMediaQueryList("screen and (max-width: 600px), print");

Options:

• maxInputLength: reject unexpectedly large input before parsing. Default: 100_000.

matchMediaQueryList(input, environment, options?)

Parses and evaluates the list against an explicit environment object.

const result = matchMediaQueryList("(hover: hover) and (pointer: fine)", {
  type: "screen",
  hover: "hover",
  pointer: "fine"
});

formatMediaQueryList(queries)

Formats parsed queries back to normalized CSS.

const parsed = parseMediaQueryList("screen and (min-width: 768px)");

if (parsed.ok) {
  console.log(formatMediaQueryList(parsed.queries));
}

Environment

type MediaQueryEnvironment = {
  type?: "all" | "screen" | "print" | "speech";
  width?: number;
  height?: number;
  resolution?: number; // dppx
  hover?: "none" | "hover";
  pointer?: "none" | "coarse" | "fine";
  color?: number;
  monochrome?: number;
};

width and height are CSS pixels. resolution is stored in dppx; 96dpi is normalized to 1.

Diagnostics

Diagnostic codes are stable strings intended for tests, logs, and UI hints:

• expected-string
• expected-environment
• invalid-options
• empty-input
• input-too-long
• empty-query
• unsupported-condition
• unsupported-media-type
• unsupported-feature
• missing-feature-value
• invalid-feature-syntax
• invalid-length
• invalid-resolution
• invalid-ratio
• invalid-number

Browser Compatibility

The core does not perform I/O, does not read global browser state, and does not depend on Node-only APIs such as fs, path, Buffer, or process.

Package quality

• TypeScript source with generated declarations.
• ESM-only package with no runtime dependencies.
• Defensive parsing API: invalid input returns diagnostics instead of throwing.
• CI runs npm ci, typecheck, build, and test.
• Tested on Node.js 20 and 22 with GitHub Actions.

License

MPL-2.0