Sebastian De Deyne

The window.matchMedia API

∙ 1 min. read ∙ #javascript

To execute a piece of code when the viewport is a certain size, the first thing that comes to mind is adding a resize event listener to the window object. This is one way, but not always the best. Sometimes the lesser known window.matchMedia API is a better fit.

This is the well-known way to trigger something in JavaScript when the viewport size changes.

window.addEventListener('resize', (event) => {
  if (window.innerWidth >= 960) {
        // …
  } else {
    // …
  }
});

The resize event is triggered whenever the viewport size changes. If the browser window is 1200px wide, and the user resizes, the callback will be called n times until they stop.

Performance issues can be solved with a debounce function to reduce the number of calls. Or, we can use the declarative matchMedia listener that will only execute when the match result changes.

window.matchMedia('(min-width: 960px)')
  .addEventListener((query) => {
    if(query.matches) {
      // …
    } else {
      // …
    }
  });

The callback will be invoked whenever query.matches changes true or false.

matchMedia is a fun little API. You can also access the current result with matches.

window.matchMedia('(min-width: 960px)').matches;

Since it’s built on media queries, you can use matchMedia for other things too—like dark mode!

window.matchMedia('(prefers-color-scheme: dark)').matches;

More JavaScript

Embed a web page with a web component and the shadow DOM

The revamped Spatie guidelines

A Tale of Client Side Framework Performance