Skip to content
A declarative responsive web design syntax. Breakpoints, defined in `<meta>`
JavaScript CSS
Find file
Latest commit 4d62014 Aug 21, 2014 @benschwarz Merge pull request #30 from benschwarz/npm
npm package?
Failed to load latest commit information.
example Merge remote-tracking branch 'CaseyLeask/extract-img-replacement' Jul 19, 2014
test Extracted the img replacement into a plugin Jul 14, 2014
.gitignore Added a .gitignore Jun 13, 2013
.jshintrc Updated grunt to 0.4.0 Jun 13, 2013
.travis.yml Tweak node versions for travis Jul 19, 2014
Gruntfile.js Added metaquery-images to grunt Jul 19, 2014
LICENSE-MIT Added everything. Jul 14, 2012 Missing paren Jul 19, 2014
bower.json Remove jquery edition of metaquery Jun 22, 2014
metaquery-images.js Added spaces around params Jul 14, 2014
metaquery-images.min.js Updated Minified versions Jul 19, 2014
metaquery.js ✔ window ✔ CJS Aug 3, 2014
metaquery.min.js ✔ window ✔ CJS Aug 3, 2014


A declarative responsive web design syntax. Breakpoints, defined in <meta> With metaquery, you define your media query breakpoints once, and only once.


— by @benschwarz

Getting Started

Install via Bower bower install metaquery

Otherwise, if you want to grab it manually:

Download the production version (416 bytes) or the development version.

  • Define your breakpoints in <meta> tags.
<meta name="breakpoint" content="phone" media="(max-width: 480px)">
<meta name="breakpoint" content="small-tablet" media="(min-width: 480px) and (max-width: 600px)">
<meta name="breakpoint" content="tablet" media="(min-width: 600px) and (max-width: 1024px)">
<meta name="breakpoint" content="widescreen" media="(min-width: 1024px)">
<meta name="breakpoint" content="retina" media="only screen and (-webkit-min-device-pixel-ratio : 2)">
  • metaQuery will add/remove classes to the <html> node (.breakpoint-<name-of-breakpoint>) for you to utilise when the breakpoints are matched. (shorter than media queries. don't repeat yourself)
  .breakpoint-phone { background: red; }
  .breakpoint-small-tablet { background: green; }
  .breakpoint-tablet { background: blue; }
  .breakpoint-widescreen { background: yellow; }
  • Responsive images in one simple line.
<img src="./images/phone.jpg" data-mq-src="./images/[breakpoint].jpg">
  test: ( !!window.matchMedia ),
  nope: ['./js/vendor/matchMedia-oldie.js']

Adding your own javascript events with metaQuery.onBreakpointChange

Considering the HTML example above, say you wanted watch for 'phone' breakpoint changes:

metaQuery.onBreakpointChange( 'phone', function ( match ) {
  if( match ) { // phawor! your media query matches. }

and if you just want to fire an event whenever you switch breakpoints (but don't care which)

metaQuery.onBreakpointChange( function (activeBreakpoints) {
    // do something amazing because you've changed breakpoints!
    // your callback will also be passed an array containing the names of active breakpoints.

Browser support

metaQuery requires matchMedia:

Otherwise, metaQuery will work with all common desktop and mobile browsers.

Browserify / CJS

metaQuery can be used with browserify.


In 2011/12 I worked on a large HTML magazine that is edited by an editorial team. Each 'module' of a template is responsive, and requires unique styles and sometimes even scripts. After reflecting on the project for some time, what worked and what didn't, I made some simple observations:

  • Writing media queries over and over again sucks. (Even though I use the technique that I illustrated back in December 11')
  • If you want media query access in javascript, you'll create yet another media query with matchMedia
  • picturefill is the best responsive image technique I've seen… until I authored templates for a massive magazine. The syntax is too long and easy to forget.
  • and finally, a summary of all three: a declarative interface is far nicer to use.

After reading both Jeremy Keith and Matt Wilcox's articles, then the source of picturefill I decided to get my hands dirty and have a go at a slightly better approach.


Please use idiomatic.js as a styleguide and take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.

Thanks to

Reviewers: Tim Lucas, Ben Alman, Jeremy Keith, Paul Irish, Divya Manian, David Desandro, Nicolas Gallagher and Mat Marquis


  • Scott Jehl for writing picturefill, matchMedia.js (with Paul Irish) and respond.js. Legend.
  • Dustin Diaz's teeny dom ready.


Copyright (c) 2012 Ben Schwarz Licensed under the MIT license.

Something went wrong with that request. Please try again.