Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

MediaQueryList: current result and the change event

MediaQueryList lets you inspect a media query's result and react when it changes. The matches property supplies the current boolean value, while the change event reports transitions between matching and not matching.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

const mql = window.matchMedia("(min-width: 600px)");
mql.matches;
mql.addEventListener("change", handler);
mql.removeEventListener("change", handler);

window.matchMedia(query) returns a MediaQueryList object describing a media query's result for the document. MediaQueryList.matches is read-only: true means a match, and false means no match. This is a property, not a method: read mql.matches, not mql.matches().

MediaQueryList.change denotes the event observed through mql.addEventListener("change", handler), not a method named mql.change(). It fires when the query result switches between true and false, not on every resize. For (min-width: 600px), a viewport width of exactly 600 CSS pixels matches; moving from 800 to 900 does not change the result. The MediaQueryListEvent passed to the handler exposes the new result as event.matches.

Registering a listener does not perform the initial update. Also read mql.matches, as the example does. When removing a component, stop listening with removeEventListener("change", handler), passing the same function reference. In the example, the change handler calls query.removeEventListener('change', handleChange) directly if event.matches is true.

This is a browser API from CSSOM View, not a feature of a particular ECMAScript edition; the repository's Node version does not establish support. MDN marks matches as widely available since July 2015 and change since September 2020. Check compatibility separately for older browsers; the deprecated addListener() is not recommended for new code.

Examples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>MediaQueryList matches and change</title>
</head>
<body>
  <script>
    const frame = document.createElement('iframe');
    frame.title = 'Media query test viewport';
    frame.style.cssText = 'display:block; width:320px; height:60px; border:0';
    frame.srcdoc = '<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Test viewport</title></head><body></body></html>';

    frame.addEventListener('load', () => {
      const query = frame.contentWindow.matchMedia('(min-width: 250px)');
      const report = matches => console.log(matches ? 'wide' : 'narrow');

      function handleChange(event) {
        report(event.matches);
        if (event.matches) {
          query.removeEventListener('change', handleChange);
        } else {
          frame.style.width = '320px';
        }
      }

      query.addEventListener('change', handleChange);
      report(query.matches);
      frame.style.width = '120px';
    }, { once: true });

    document.body.append(frame);
  </script>
</body>
</html>

Result

wide
narrow
wide

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources