Media query listeners

  • Article

Windows Internet Explorer 9 introduced support for Cascading Style Sheets, Level 3 (CSS3) media queries to change element styles, such as font size or margins, based on the device or media. New to Internet Explorer 10 and Windows apps using JavaScript, media query listeners allow you to use script to react to changes in the media or environment in which your page is running.

Media query listeners are specified in Section 4.1 of the CSSOM View Module, which is currently a World Wide Web Consortium (W3C) Working Draft.

For a hands-on demonstration of media query listeners, see CSS3 Media Queries & Media Query Listeners on the IE Test Drive.

Media query listeners enable two new capabilities, described later in this topic:

  • Evaluating a media query at runtime using JavaScript
  • Subscribing listeners to changes in the media query's evaluation

This topic contains the following sections:

  • Creating a media query listener
  • Subscribing media query listeners
  • Related topics

Creating a media query listener

To evaluate a media query at run time, an MediaQueryList object is created using the new window method, matchMedia.

Method Description

matchMedia(sList)

Accepts a string that contains one or more media queries, and returns an MediaQueryList object.

 

The matchMedia method accepts a media query string and returns a MediaQueryList object. The following example creates a media query that checks whether the width or height of a window is less than a certain size.

mql = window.msMatchMedia("(min-width:450px)");

The MediaQueryList object provides the following properties.

Property Description

matches

Returns "true" if the list of media queries matches the state of the current window; returns "false" otherwise.

media

Returns the serialized version of the media query list, which was used to create the MediaQueryList object.

 

The MediaQueryList object provides the following methods.

Method Description

addListener(callback)

Adds the callback function to the list of listeners for the MediaQueryList object. The function is called whenever the evaluation of the media query changes.

removeListener(callback)

Removes the given callback function from the list of listeners for this MediaQueryList object.

 

The matches property is a Boolean value that returns an evaluation of the media query. Using the example above, matches returns true if the window's width is greater than or equal to the minimum that has been specified.

if (mql.matches) 
{
  // Window is fine. 
} else 
{
  // Window is too narrow.       
}

Subscribing media query listeners

To detect media query changes, you can subscribe a listener to a MediaQueryList object. The addListener method takes a callback function, and invokes it when the media query changes evaluation. Using the previous media query, the following example subscribes to changes in the media query.

mql.addListener(sizeChange); // Size change is the callback function.function sizeChange(mql) 
{
  if (mql.matches) 
  {
    // The window is big enough for content.
  } 
  else 
  {
    // The window has gotten too small for content.
  }
}

The listener invokes the callback function whenever the state of the media actually changes. If the window is resized to be narrower than the specified minwidth attribute value, the callback function is invoked. It is invoked again when the window becomes wider than our min-width. The MediaQueryList object is passed as a parameter to the callback function.

Document Object Model (DOM)

Internet Explorer 10 Guide for Developers