MediaQueryList
==============

A **`MediaQueryList`** object stores information on a media query applied to a document, with support for both immediate and event-driven matching against the state of the document.

You can create a `MediaQueryList` by calling `matchMedia()` on the `window` object. The resulting object handles sending notifications to listeners when the media query state changes (i.e. when the media query test starts or stops evaluating to `true`).

This is very useful for adaptive design, since 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.

EventTarget

MediaQueryListInstance properties
-------------------

*The `MediaQueryList` interface inherits properties from its parent interface, `EventTarget`.*

`matches` Read only 

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

`media` Read only 

A string representing a serialized media query.

Instance methods
----------------

*The `MediaQueryList` interface inherits methods from its parent interface, `EventTarget`.*

`addListener()` 
Deprecated

Adds to the `MediaQueryList` a callback which is invoked whenever the media query status—whether or not the document matches the media queries in the list—changes. This method exists primarily for backward compatibility; if possible, you should instead use `addEventListener()` to watch for the `change` event.

`removeListener()` 
Deprecated

Removes the specified listener callback from the callbacks to be invoked when the `MediaQueryList` changes media query status, which happens any time the document switches between matching and not matching the media queries listed in the `MediaQueryList`. This method has been kept for backward compatibility; if possible, you should generally use `removeEventListener()` to remove change notification callbacks (which should have previously been added using `addEventListener()`).

Events
------

*The following events are delivered to `MediaQueryList` objects:*

`change`

Sent to the `MediaQueryList` when the result of running the media query against the document changes. For example, if the media query is `(min-width: 400px)`, the `change` event is fired any time the width of the document's viewport changes such that its width moves across the 400px boundary in either direction.

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 appearance of the page.


```js
const para = document.querySelector("p");
const 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 600 pixels wide \*/
    para.textContent = "This is a wide screen — more than 600px wide.";
    document.body.style.backgroundColor = "blue";
  }
}

mql.addEventListener("change", screenTest);
```


**Note:** You can find this example on GitHub (see the source code, and also see it running live).

You can find other examples on the individual property and method pages.

Specifications
--------------

| Specification |
| --- |
| CSSOM View Module # the-mediaquerylist-interface |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Media queries
* Using media queries from code
* `window.matchMedia()`
* `MediaQueryListEvent`
* The article `Window.devicePixelRatio` also has a useful example