A nicer JavaScript media query API.

Usage no npm install needed!

<script type="module">
  import mediaQueryFacade from '';



build status coverage status npm version npm downloads

Do stuff via JavaScript when the media queries on a document change. For efficiency it uses window.matchMedia under the hood.


import MQFacade from 'media-query-facade'

const mq = new MQFacade({
  small: 'only screen and (max-width: 480px)',
  medium: 'only screen and (min-width: 480px) and (max-width: 720px)'

const changeColour = colour => () => { = colour

mq.on('small', changeColour('blue'))
mq.on('medium', changeColour('green'))
mq.on('only screen and (min-width: 720px)', changeColour('red'))

There is a working version of the above in the example dir. First run npm start, then point a browser at localhost:8080.


const mq = new MQFacade(aliases)

Initialise a new MQFacade. Media query aliases may also be provided up front.

mq.registerAlias(alias, query)

Register an alias for a query, or register a number of aliases at once via an object.

mq.registerAlias('small', '(max-width: 100px)')
  small: '(max-width: 100px)',
  medium: '(max-width: 200px)'

mq.on(query, callback, context)

Register a callback which will be executed with the given context on entry of the given query or alias. If context is not specified, it will default to the mq instance.

mq.on('(max-width: 400px)', () => {})
mq.on('smartphones', () => {}, {}), callback, context)

Remove all callbacks for all queries:

Remove all callbacks for a query or alias:'(max-width: 400px)')

Remove a callback for a query or alias:'(max-width: 400px)', () => {})

Remove a callback with a context for a query or alias:'(max-width: 400px)', () => {}, {})


$ npm install media-query-facade --save

There are also UMD builds available via unpkg: