window.matchMedia() returns a MediaQueryList for a CSS media query string so you can check if the document matches (MDN). Read .matches, or listen for change when the result flips.
Pass the required arguments shown below. Check return values and browser support before you rely on the result.
Call window.matchMedia. Start with this line.
matchMedia(mediaQueryString)| Call | What it does |
|---|---|
matchMedia(mediaQueryString) | Primary signature. |
window.matchMedia(...) | Call with the arguments your case needs. |
Built into the browser. Call window.matchMedia(...) (or the global matchMedia(...)) — no import required.
matchMedia(mediaQueryString)| Parameter | Description |
|---|---|
| mediaQueryString | Required. CSS media query to parse |
| change event | Optional. Fires when match result flips |
| Return Value | Description |
|---|---|
| * | MediaQueryList object |
matchesCheck whether the viewport is 600px wide or less.
const mql = window.matchMedia("(width <= 600px)");
console.log(mql.matches); // true or falseMediaQueryList.matches. Boolean for the current document.change ListenerUpdate text whenever the match result flips (for example on resize).
const mql = window.matchMedia("(min-width: 600px)");
function onChange(e) {
console.log(e.matches ? "wide enough" : "too narrow");
}
onChange(mql); // initial
mql.addEventListener("change", onChange);matchMedia call.addEventListener("change", ...).e.matches. The event carries the new boolean.Choose compact vs full UI from a max-width query.
const mobile = window.matchMedia("(max-width: 767px)");
if (mobile.matches) {
console.log("Mobile layout");
} else {
console.log("Desktop layout");
}matches. Keep JS and CSS breakpoints aligned.change listener for live switches.Detect the user’s prefers-color-scheme: dark setting.
const dark = window.matchMedia("(prefers-color-scheme: dark)");
console.log(dark.matches ? "Dark preferred" : "Light preferred");
dark.addEventListener("change", function (e) {
console.log(e.matches ? "Switched to dark" : "Switched to light");
});matches is the current preference.change fires if the user flips OS theme.Skip fancy animation when the user prefers reduced motion.
const reduce = window.matchMedia("(prefers-reduced-motion: reduce)");
if (reduce.matches) {
console.log("Skip animation");
} else {
console.log("Play intro animation");
}prefers-reduced-motion.matches is true.@media.Window.matchMedia() is marked Baseline Widely available on MDN (since July 2015). Browser Window API — not a Node.js built-in.
Test CSS media queries from JavaScript across modern browsers.
Bottom line: Safe for responsive JS. Prefer addEventListener('change') over legacy addListener.
Move the browser window by a relative offset.
8 people found this page helpful