Skip to content
Improve the way you handle your media queries listeners in JavaScript.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Adding circleci config for version 2 Oct 18, 2018
dist Fixing typos Oct 22, 2018
src
tests
.babelrc Refactoring, making MQS better Oct 19, 2018
.gitignore adding coverage to .gitignore Oct 18, 2018
.prettierrc Adds base implementation of MQS Oct 16, 2018
LICENSE Adding license file Oct 18, 2018
README.md Adding clarification for advantages of using MQS. Nov 5, 2018
config.json adding first implementation for coveralls Oct 18, 2018
package.json Adding demo page and bumping version Oct 22, 2018
webpack.config.js
yarn.lock Refactoring, making MQS better Oct 19, 2018

README.md

MediaQuerySensor · GitHub license npm version Coverage Status CircleCI

MediaQuerySensor (MQS) is a very simple and powerful event wrapper that allows you to add listeners to your site or app, it will basically execute functions based on media query/breakpoints specified by you.

Instead of adding a listener to the window's resize event, MQS creates a wrapper around the window property window.matchMedia which makes it fast and performant.

Why to use MQS?, what problems does it solve?

The problem:

In today's world to be able to remove and add listeners to media queries you first need to follow some steps:

  1. Create a MediaQueryList object.
  2. Bind a function to the object created through a listener.
  3. Check when the screen matches the media query to execute the function in the listener.
  4. If you want to be able to remove a listener you will need to make sure that the reference to the MediaQueryList object and the function is still available in your current scope since both are needed to achieve this. If you don't have access to the references you will have to define global variables and make changes in your code that could be avoided.

Solution:

MQS simplifies your life when working with media query listeners and also solves the scoping problem:

  1. It takes care of creating the MediaQueryList objects.
  2. It takes the responsability of binding your objects with your functions through a listener.
  3. It makes the necessary checks to execute your functions when the screen size matches a media query.
  4. It creates accesible references so that you can remove listeners everywhere without having to worry about the context you're currently in.

Installation

Use the package manager of your preference:

npm: npm install mediaquerysensor

yarn: yarn add mediaquerysensor

Include it directly in the browser with a CDN:

https://cdn.jsdelivr.net/npm/mediaquerysensor@2.0.1/dist/mediaquerysensor.min.js

Demo

A demo is available at https://enmascript.com/code/mediaquerysensor

Usage

MediaQuerySensor exposes the MQS API in the window object if you include the library in your project using a script tag. If you desire to use it as a npm module, you can just import it and use it in the same way in your code.

Adding a sensor/listener:

To add a Sensor or Listener we use the method MQS.add({ref, mediaQuery, action}), this method takes an object as argument with the next properties:

Property type Description
ref Object key A valid (UNIQUE) object key (preferably a String) assigned as identifier to each pair (mediaQuery and action) passed to MQS, this will allow us to remove listeners when necessary.
mediaQuery String:MediaQueryString MediaQuery in which the action is going to be executed (You can define media queries in the same way as CSS Media queries).
action Function Function to execute when the media query conditions are fullfilled.

Example

import MQS from 'mediaquerysensor';

MQS.add({
    ref: 'yourRef',
    mediaQuery: '(min-width: 991px) and (min-height: 500px)', // Your Media Query
    action: () => {} /* Your function to execute */
});

Another example using a previously defined action:

const consoleLogger = () => console.log('Between 480px and 990px');

MQS.add({
    ref: 'yourRef2',
    mediaQuery: '(min-width: 480px) and (max-width: 990px)',
    action: consoleLogger
});

Removing a sensor/listener:

To remove individual sensors we use the method MQS.remove(ref), this method takes the next argument:

argument type Description
ref Valid Object key, preferably a string Matching UNIQUE key used when adding the sensor.

Example

import MQS from 'mediaquerysensor';

MQS.remove('yourRef');

Remove all sensors/listeners

MQS also provides the ability to remove all the added sensors programatically by using the method MQS.empty():

Example

import MQS from 'mediaquerysensor';

MQS.empty();

Checking/Getting active sensors

To help you make validations and find problems in your implementations there is also a MQS.get() method available that exposes an object with all the active sensor's properties, you can also get one specific sensor object directly to see if it is active by executing MQS.get()['sensorRef'].

Example

import MQS from 'mediaquerysensor';

// Gets an object with all the active sensors
MQS.get();

// Gets a sensor object identified by the key "sensorRef"
MQS.get()['sensorRef'];

// You may want to console.log it sometimes
console.log(MQS.get());

How it works

MQS receives an object with the properties ref, mediaQuery and action to create sensors (as previously seen on the add method).

What is a Sensor?

A sensor is just an object created by MQS that contains the properties mediaQuery and action defined, each sensor uses the ref value defined by you as identifier. Once a sensor is created, a listener is added to bind your mediaQuery with your action together so that they can be executed when the screen matches the mediaQuery conditions. Also, you'll see that each sensor object contains two extra properties:

argument type Description
mediaQueryList MediaQueryList Object It's required to use the matchMedia API, this object allows us to add and remove listeners.
boundAction Function The final function bound to the mediaQueryList listeners, this function contains the validations of when an action should be executed.

So, if we call the method add like:

MQS.add({
    ref: 'refId',
    mediaQuery: '(max-height: 400px)',
    action: () => console.log('maximum of 400px of height'),
});

MQS.add({
    ref: 'refId2',
    mediaQuery: '(min-width: 768px) and (max-width: 990px)',
    action: () => console.log('768px to 990px'),
});

It will create the following sensor objects:

{
    'refId': {
        mediaQuery: '(max-height: 400px)',
        action: () => console.log('maximum of 400px of height'),
        mediaQueryList: MediaQueryList{},
        boundAction: () => {}
    },
    'refId2': {
        mediaQuery: '(min-width: 768px) and (max-width: 990px)',
        action: () => console.log('768px to 990px of width'),
        mediaQueryList: MediaQueryList{},
        boundAction: () => {}
    }
}

Browsers support

As I said before, this library is a wrapper around matchMedia which has a great support for browsers.

You can’t perform that action at this time.