Web/CSS/Media Queries/Testing media queries

The DOM provides features that can test the results of a media query programmatically, via the MediaQueryList interface and its methods and properties. Once you've created a MediaQueryList object, you can check the result of the query or receive notifications when the result changes.

Creating a media query list

Before you can evaluate the results of a media query, you need to create the MediaQueryList object representing the query. To do this, use the window.matchMedia method.

For example, to set up a query list that determines if the device is in landscape or portrait orientation:

const mediaQueryList = window.matchMedia("(orientation: portrait)");

Checking the result of a query

Once you've created your media query list, you can check the result of the query by looking at the value of its matches property:

if (mediaQueryList.matches) {
  /* The viewport is currently in portrait orientation */
} else {
  /* The viewport is not currently in portrait orientation, therefore landscape */
}

Receiving query notifications

If you need to be aware of changes to the evaluated result of the query on an ongoing basis, it's more efficient to register a listener than to poll the query's result. To do this, call the addListener() method on the MediaQueryList object, with a callback function to invoke when the media query status changes (e.g., the media query test goes from true to false):

// Create the query list.
const mediaQueryList = window.matchMedia("(orientation: portrait)");

// Define a callback function for the event listener.
function handleOrientationChange(mql) {
  // ...
}

// Run the orientation change handler once.
handleOrientationChange(mediaQueryList);

// Add the callback function as a listener to the query list.
mediaQueryList.addListener(handleOrientationChange);

This code creates the orientation-testing media query list, then adds an event listener to it. After adding the listener, we also call the listener directly. This makes our listener perform adjustments based on the current device orientation; otherwise, our code might assume the device is in portrait mode at startup, even if it's actually in landscape mode.

The handleOrientationChange() function would look at the result of the query and handle whatever we need to do on an orientation change:

function handleOrientationChange(evt) {
  if (evt.matches) {
    /* The viewport is currently in portrait orientation */
  } else {
    /* The viewport is currently in landscape orientation */
  }
}

Above, we define the parameter as evt — an event object. This makes sense because newer implementations of MediaQueryList handle event listeners in a standard way. They no longer use the unusual MediaQueryListListener mechanism, but a standard event listener setup, passing an event object of type MediaQueryListEvent as the argument to the callback function.

This event object also includes the media and matches properties, so you can query these features of the MediaQueryList by directly accessing it, or accessing the event object.

Ending query notifications

To stop receiving notifications about changes to the value of your media query, call removeListener() on the MediaQueryList, passing it the name of the previously-defined callback function:

mediaQueryList.removeListener(handleOrientationChange);

Browser compatibility

MediaQueryList interface

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
MediaQueryList	Chrome Full support 9	Edge Full support 12	Firefox Full support 6	IE Full support 10	Opera Full support 12.1	Safari Full support 5.1 Notes' Full support 5.1 Notes' Notes' Prior to Safari 14, MediaQueryList is based on EventTarget, so you must use addListener() and removeListener() to observe media query lists.	WebView Android Full support Yes	Chrome Android Full support 18	Firefox Android Full support Yes	Opera Android Full support Yes	Safari iOS Full support 5 Notes' Full support 5 Notes' Notes' Prior to Safari 14, MediaQueryList is based on EventTarget, so you must use addListener() and removeListener() to observe media query lists.	Samsung Internet Android Full support 1.0
EventListener objects as parameters	Chrome Full support 45	Edge Full support ≤79	Firefox Full support 55	IE No support No	Opera No support No	Safari ?	WebView Android Full support 45	Chrome Android Full support 45	Firefox Android Full support 55	Opera Android No support No	Safari iOS ?	Samsung Internet Android Full support 5.0
MediaQueryList inherits EventTarget	Chrome Full support 45	Edge Full support 16	Firefox Full support 55	IE No support No	Opera Full support Yes	Safari No support No	WebView Android Full support 45	Chrome Android Full support 45	Firefox Android Full support 55	Opera Android Full support Yes	Safari iOS No support No	Samsung Internet Android Full support 5.0
addListener()	Chrome Full support 9	Edge Full support 12	Firefox Full support 6	IE Full support 10	Opera Full support 12.1	Safari Full support 5.1 Notes' Full support 5.1 Notes' Notes' Prior to Safari 14, MediaQueryList is based on EventTarget, so you must use addListener() and removeListener() to observe media query lists.	WebView Android Full support Yes	Chrome Android Full support 18	Firefox Android Full support Yes	Opera Android Full support Yes	Safari iOS Full support 5 Notes' Full support 5 Notes' Notes' Prior to Safari 14, MediaQueryList is based on EventTarget, so you must use addListener() and removeListener() to observe media query lists.	Samsung Internet Android Full support 1.0
matches	Chrome Full support 9	Edge Full support 12	Firefox Full support 6	IE Full support 10	Opera Full support 12.1	Safari Full support 5.1	WebView Android Full support Yes	Chrome Android Full support 18	Firefox Android Full support Yes	Opera Android Full support Yes	Safari iOS Full support 5	Samsung Internet Android Full support 1.0
media	Chrome Full support 9	Edge Full support 12	Firefox Full support 6	IE Full support 10	Opera Full support 12.1	Safari Full support 5.1	WebView Android Full support Yes	Chrome Android Full support 18	Firefox Android Full support Yes	Opera Android Full support Yes	Safari iOS Full support 5	Samsung Internet Android Full support 1.0
onchange	Chrome Full support 45	Edge Full support ≤79	Firefox Full support 55	IE No support No	Opera Full support Yes	Safari Full support 14	WebView Android Full support 45	Chrome Android Full support 45	Firefox Android Full support 55	Opera Android Full support Yes	Safari iOS Full support 14	Samsung Internet Android Full support 5.0
removeListener()	Chrome Full support 9	Edge Full support 12	Firefox Full support 6	IE Full support 10	Opera Full support 12.1	Safari Full support 5.1 Notes' Full support 5.1 Notes' Notes' Prior to Safari 14, MediaQueryList is based on EventTarget, so you must use addListener() and removeListener() to observe media query lists.	WebView Android Full support Yes	Chrome Android Full support 18	Firefox Android Full support Yes	Opera Android Full support Yes	Safari iOS Full support 5 Notes' Full support 5 Notes' Notes' Prior to Safari 14, MediaQueryList is based on EventTarget, so you must use addListener() and removeListener() to observe media query lists.	Samsung Internet Android Full support 1.0

Legend

Full support  

Full support

No support  

No support

Compatibility unknown  

Compatibility unknown

See implementation notes.'

See implementation notes.

See also

• Media queries
• window.matchMedia()
• MediaQueryList
• MediaQueryListEvent

Testing media queries programmatically by Mozilla Contributors is licensed under CC-BY-SA 2.5.