MediaQueryList

A MediaQueryList object stores information on a media query applied to a document, and handles sending notifications to listeners when the media query state change (i.e. when the media query test starts or stops evaluating to true).

This makes it possible to observe a document to detect when its media queries change, instead of polling the values periodically, and allows you to programmatically make changes to a document based on media query status.

Properties

The new version of the MediaQueryList interface inherits properties from its parent interface, EventTarget.

MediaQueryList.matches Read only

A Boolean that returns true if the document currently matches the media query list, or false if not.

MediaQueryList.media Read only

A DOMString representing a serialized media query.

Event handlers

MediaQueryList.onchange

An event handler property representing a function that is invoked when the change event fires, i.e when the status of media query support changes. The event object is a MediaQueryListEvent instance, which is recognised as a MediaListQuery instance in older browsers, for backwards compatibility purposes.

Methods

The new version of the MediaQueryList interface inherits methods from its parent interface, EventTarget.

MediaQueryList.addListener()

Adds a listener to the MediaQueryListener that will run a custom callback function in response to the media query status changing. This is basically an alias for EventTarget.addEventListener(), for backwards compatibility purposes.

MediaQueryList.removeListener()

Removes a listener from the MediaQueryListener. This is basically an alias for EventTarget.removeEventListener(), for backwards compatibility purposes.

Examples

This simple example creates a MediaQueryList and then sets up a listener to detect when the media query status changes, running a custom function when it does to change the appearence of the page.

var para = document.querySelector('p');

var mql = window.matchMedia('(max-width: 600px)');

function screenTest(e) {
  if (e.matches) {
    /* the viewport is 600 pixels wide or less */
    para.textContent = 'This is a narrow screen — less than 600px wide.';
    document.body.style.backgroundColor = 'red';
  } else {
    /* the viewport is more than than 600 pixels wide */
    para.textContent = 'This is a wide screen — more than 600px wide.';
    document.body.style.backgroundColor = 'blue';
  }
}

mql.addListener(screenTest);

Specifications

Browser compatibilityUpdate compatibility data on GitHub

See also

• Media queries
• Using media queries from code
• window.matchMedia()
• MediaQueryListListener
• MediaQueryListEvent