Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Browser and Web APIs

The window.matchMedia() method

Reference for window.matchMedia(): test CSS media queries from JavaScript, react to changes with the change event, and read user preferences safely.

window.matchMedia() takes a CSS media query string and returns a MediaQueryList object. Its matches property tells you whether the query is true right now, and the object fires a change event whenever the answer flips. It is the JavaScript counterpart of @media rules in CSS.

Use it for things CSS cannot do alone: switching a component's behavior at a breakpoint, reading prefers-color-scheme or prefers-reduced-motion, or checking whether the primary input can hover.

JavaScript
const wide = matchMedia("(min-width: 800px)");
console.log(wide.matches);

Try it

Live breakpoint and preferences
Run code only when a breakpoint changes

The change event only fires when the result switches between true and false, not on every pixel of resizing, so there is no need to debounce it.

Syntax

JavaScript
window.matchMedia(mediaQueryString)

mql.matches      // boolean
mql.media        // the serialized query
mql.addEventListener("change", (event) => { /* event.matches */ });
Name Description
mediaQueryString A valid media query such as "(min-width: 40rem)" or "screen and (orientation: portrait)". Do not include @media.

Return value: a MediaQueryList with matches, media, and addEventListener() / removeEventListener(). The older addListener() and removeListener() still exist but are deprecated.

Exceptions: none for invalid queries. An invalid string produces a list whose media is "not all" and whose matches is false.

Usage notes

  • matches is live. Read it whenever you need the current answer; you do not have to create a new object.
  • Use em or rem in width queries to match your CSS exactly, including when users change their default font size.
  • Prefer CSS when possible. If you only need different styles, a CSS @media rule is simpler and avoids JavaScript. Use matchMedia() when behavior changes: loading different code, starting or stopping an animation, or choosing a data layout.
  • Respect user preferences. Check prefers-reduced-motion: reduce before running large animations, and prefers-color-scheme to sync custom theme code with the system setting.
  • hover: hover and pointer: fine describe the primary input device. They are better guides than user-agent sniffing, but hybrid devices can have both touch and mouse.
  • Remove listeners with removeEventListener() when a component goes away, using the same function reference.
  • The initial state is not an event. Call your handler once yourself, as in the examples above.
  • Inside iframes the query measures the iframe's viewport, not the whole browser window.

Browser support

matchMedia() is supported in every current browser. The addEventListener() form on MediaQueryList is in all modern ones; very old browsers only had addListener().