ts-mq (typesafe media queries)

Typesafe CSS media query generation. Generate simple or complex CSS media queries using JavaScript objects and helper functions. Inspired by json2mq.

Install

pnpm add ts-mq

Basic Usage

import { mq } from 'ts-mq';

const query = mq({ type: 'only screen', maxWidth: 600 });

Pass an object into mq specifying the features you want to apply. This object is a union of all non-deprecated media types and features specified in the MDN docs. By default, mq will add an and operator between features.

Type Property

The type property refers to the media type you want to apply to a query. This property is described by the MediaType type (see type definition).

This property can take one of the following values:

String

mq({ type: 'only screen', minWidth: 100 });

The three basic media types (screen, print and all) along with their not and only counterparts. The example above will generate only screen and (min-width: 100px).

Array of Strings

mq({ type: ['screen', 'print'], minWidth: 100 });

The three basic media types seperated by a comma. The example above will generate screen, print and (min-width: 100px).

Width, Height and Resolution

mq({
  width: 100,
  minWidth: '100em',
  maxWidth: {
    value: 200,
    units: 'rem'
  }
});

The example above will generate (width: 100px) and (min-width: 100em) and (max-width: 200rem).

The width, height and resolution properties (along with their min and max counterparts) can take one of three argument types.

1. string - A string argument will be returned exactly as it's provided. mq will assume you've added a correct unit.
2. number - A number argument will trigger mq to add a default unit to the end (see constants).
3. UnitInput - A Unit Input is a custom object type which takes both a value and a units property. The value property requires a number, and the units property requires a typesafe unit.

Helper Functions

const query = mq(({ and, or, not }) => ...)

For more advanced cases, you can destructure three helper functions: and, or and not. These helpers can take an unrestricted number of arguments.

mq(({ and, or }) => or(and({ minWidth: 100, maxWidth: 200 }), and({ minWidth: 300, maxWidth: 400 })));

and, or link features using the relavant operator (in CSS media queries a comma is equivalent to an or operator). The example above will generate (((min-width: 100px) and (max-width: 200px)) or ((min-width: 300px) and (max-width: 400px)))

mq(({ not }) => not({ minWidth: 100, maxWidth: 200 }));

not wraps its content in a not operator and by default links them using an and operator. The above example will generate not ((min-width: 100px) and (max-width: 200px))

Other Helpers

executeMediaQuery

ts-mq includes an executeMediaQuery function to test queries on the browser.

import { executeMediaQuery, mq } from 'ts-mq';

const query = mq({ type: 'only screen', minWidth: 100, maxWidth: 200 });
const executed = executeMediaQuery(query);

If the window object exists, window.matchMedia will run, otherwise a false is returned by default.

import { addChangeListener, executeMediaQuery, mq } from 'ts-mq';

const query = mq({ type: 'only screen', minWidth: 100, maxWidth: 200 });
const matchMedia = window.matchMedia(mq);
const executed = executeMediaQuery(matchMedia);

// you can now use the same object for event listeners
matchMedia.addEventListener('change', () => {});
// alternatively
addChangeListener(matchMedia, () => {});

Alternatively, you can provide a window.matchMedia return object as an argument to executeMediaQuery. This is more useful for using the same object for creating event listeners.

Event Listeners

ts-mq also provides two basic event listeners to listen for changes in browser dimensions and re-test media queries.

import { addChangeListener, executeMediaQuery, MediaQueryEventListener, mq, removeChangeListener } from 'ts-mq';

const query = mq({ type: 'only screen', minWidth: 600 });

const eventListener: MediaQueryEventListener = (executed, query) => {
  console.log('query media match: ', query, executed);
};

addChangeListener(query, eventListener);
removeChangeListener(query, eventListener);

Both addChangeListener and removeChangeListener require two arguments: the first a query to watch, the second a listener function of the MediaQueryEventListener type and returns no value. The query argument, like with executeMediaQuery can either be a query string to execute, or a window.matchMedia return object.

MediaQueryEventListener

MediaQueryEventListener is a type representing the callback type for ts-mq's event listeners. This function has take two arguments: the first is a boolean value representing the executed query state, and the second the query as a string.