HTML & CSS

How to use Media Queries in JavaScript with matchMedia

Craig Buckler
Share

This article from 2011 was updated in 2018.

When it was first introduced, responsive design was one of the most exciting web layout concepts since CSS replaced tables. The underlying technology uses media queries to determine the viewing device type, width, height, orientation, resolution, aspect ratio, and color depth to serve different stylesheets.

If you thought responsive design was reserved for CSS layouts only, you’ll be pleased to hear media queries can also be used in JavaScript, as this article will explain.

Media Queries in CSS

In the following example, cssbasic.css is served to all devices. But, if it’s a screen with a horizontal width of 500 pixels or greater, csswide.css is also sent:

<link rel="stylesheet" media="all" href="cssbasic.css" />
<link rel="stylesheet" media="(min-width: 500px)" href="csswide.css" />

The possibilities are endless and the technique has long been exploited by most websites out there on the Internet. Resizing the width of your browser triggers changes in the layout of the webpage.

With media queries nowadays it’s easy to adapt the design or resize elements in CSS. But what if you need to change the content or functionality? For example, on smaller screens you might want to use a shorter headline, fewer JavaScript libraries, or modify the actions of a widget.

It’s possible to analyze the viewport size in JavaScript but it’s a little messy:

  • Most browsers support window.innerWidth and window.innerHeight. (IE before version 10 in quirks mode required document.body.clientWidth and document.body.clientHeight.)
  • window.onresize
  • All the main browsers support document.documentElement.clientWidth and document.documentElement.clientHeight but it’s inconsistent. Either the window or document dimensions will be returned depending on the browser and mode.

Even if you successfully detect viewport dimension changes, you must calculate factors such as orientation and aspect ratios yourself. There’s no guarantee it’ll match your browser’s assumptions when it applies media query rules in CSS.

How to Write Media Queries with JavaScript Code

Fortunately, it’s possible to respond to CSS3 media query state changes within JavaScript. The key API is window.matchMedia. This is passed a media query string identical to those used in CSS media queries:

const mq = window.matchMedia( "(min-width: 500px)" );

The matches property returns true or false depending on the query result. For example:

if (mq.matches) {
// window width is at least 500px
} else {
// window width is less than 500px
}

You can also add an event listener which fires when a change is detected:

// media query event handler
if (matchMedia) {
const mq = window.matchMedia("(min-width: 500px)");
mq.addListener(WidthChange);
WidthChange(mq);
}

// media query change
function WidthChange(mq) {
if (mq.matches) {
// window width is at least 500px
} else {
// window width is less than 500px
}

}

You should also call the handler directly after defining the event. This will ensure your code can initialize itself during or after the page has loaded. Without it, WidthChange() would never be called if the user did not change their browser dimensions.

At the time of writing, matchMedia has excellent browser support across the board, so there’s no reason why you can’t use it in production.

Check how the text dynamically changes in the demo below from more than 500 pixels to less than 500 pixels as you resize your browser window. Alternatively, download the sample code:

See the Pen CSS Media Queries with JavaScript by SitePoint (@SitePoint) on CodePen.