JavaScript Window matchMedia() Method

What You’ll Learn

The matchMedia() method lets JavaScript test the same media queries you use in CSS. This tutorial covers syntax, the MediaQueryList object, listening for change events, five examples, and patterns for responsive UI and user preferences.

Introduction

Responsive websites adapt layout with CSS @media rules. Sometimes JavaScript also needs to know whether a breakpoint matches— to swap components, load a mobile menu module, or respect the user’s dark-mode preference. window.matchMedia() bridges CSS media queries and JavaScript logic.

Instead of comparing raw pixel widths with window.innerWidth, you pass a media query string like "(min-width: 768px)". The browser returns a MediaQueryList whose matches property tells you the current result, and whose change event fires when that result flips.

Understanding the matchMedia() Method

Call window.matchMedia(mediaQueryString) with a valid media query (usually wrapped in parentheses). The return value is a live MediaQueryList object—not a boolean. Read mediaQueryList.matches for the yes/no answer at this moment.

Register addEventListener("change", handler) on that object so your script reacts when the user resizes the window, rotates a phone, or changes system settings that affect the query.

📝 Syntax

General form of Window.matchMedia():

const mq = window.matchMedia(mediaQueryString);
// shorthand (same in browsers):
const mq = matchMedia("(min-width: 768px)");

Parameters

• mediaQueryString (required) — a string containing a media query, e.g. "(max-width: 767px)" or "(prefers-color-scheme: dark)".

Return value

• A MediaQueryList with at least:
  • matches — boolean, whether the query is true now.
  • media — the query string you passed.

Common patterns

• if (matchMedia("(min-width: 600px)").matches) { … } — one-time check.
• mq.addEventListener("change", onChange) — respond to updates.
• matchMedia("(prefers-reduced-motion: reduce)").matches — accessibility preference.

Examples Gallery

Each snippet tests a media query and logs or updates UI based on matches. Resize the Try-it preview or change system theme to see change events fire.

const mediaQuery = window.matchMedia("(min-width: 600px)");

if (mediaQuery.matches) {
  console.log("Viewport width is at least 600 pixels.");
} else {
  console.log("Viewport width is less than 600 pixels.");
}

≥ 600px → Viewport width is at least 600 pixels.
< 600px → Viewport width is less than 600 pixels.

const mediaQuery = window.matchMedia("(min-width: 600px)");

function handleChange(mq) {
  if (mq.matches) {
    console.log("Now at least 600px wide.");
  } else {
    console.log("Now less than 600px wide.");
  }
}

handleChange(mediaQuery);
mediaQuery.addEventListener("change", handleChange);

Now at least 600px wide.
(or)
Now less than 600px wide.

const mobileQuery = window.matchMedia("(max-width: 767px)");

if (mobileQuery.matches) {
  console.log("Mobile layout — enable compact menu.");
} else {
  console.log("Desktop layout — show full navigation.");
}

≤ 767px → Mobile layout — enable compact menu.
> 767px → Desktop layout — show full navigation.

const darkModeQuery = window.matchMedia("(prefers-color-scheme: dark)");

if (darkModeQuery.matches) {
  console.log("Dark mode preference detected.");
  document.body.classList.add("theme-dark");
} else {
  console.log("Light mode preference detected.");
  document.body.classList.remove("theme-dark");
}

Dark OS theme → Dark mode preference detected.
Light OS theme → Light mode preference detected.

const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)");

function runIntroAnimation() {
  if (reduceMotion.matches) {
    console.log("Skipping animation — reduced motion preferred.");
    return;
  }
  console.log("Playing intro animation.");
}

runIntroAnimation();

Reduce motion ON → Skipping animation — reduced motion preferred.
Reduce motion OFF → Playing intro animation.

🚀 Common Use Cases

• Responsive components — mount mobile vs desktop widgets at the same breakpoint as CSS.
• Conditional loading — import heavy chart libraries only on large screens.
• Dark / light themes — sync JavaScript charts or maps with prefers-color-scheme.
• Accessibility — honor prefers-reduced-motion and prefers-contrast.
• Orientation — detect (orientation: landscape) for canvas games or video players.
• Analytics — log which breakpoint bucket the user is in without polling resize constantly.

📝 Notes

• Prefer CSS for layout changes; use JS when behavior—not just appearance—must change.
• The change event handler receives a MediaQueryListEvent with a matches property.
• Invalid query strings may throw or match nothing—test queries in DevTools first.
• matchMedia is not available in Node.js without a DOM; use it in browsers.
• Combine multiple conditions: "(min-width: 768px) and (prefers-reduced-motion: no-preference)".
• Remove listeners in single-page apps when components unmount to avoid leaks.

💡 Best Practices