respondto
A simple and lightweight JavaScript API for applying (and unapplying) DOM changes (or any arbitray JS code) based on defined media query conditions.
Or, as I like to say: media queries for JavaScript!
Usage
respondto exposes one property on the window
object. As you'd probably guess, it's named respondto
. It allows you to register (and unregister) media query conditions around which you can create JavaScript based behavior. I call these responders.
Responders
respondto.addResponder
takes a single parameter representing the responder. A responder is any object with two required properties, query
and apply
, and one optional callback property, unapply
.
The query
property is a string representing a valid media query. For example: '(max-width: 500px)'
Applying and unapplying
The remaining two properties, apply
and unapply
are callback functions that will be executed accordingly.
Each time a new responder is registered (remember, this happens by calling respondto.addResponder
), the system checks to see if the given query
currently applies --- e.g. given a query
value of max-width: 500px
the system will immediately test whether the media query's condition is currently met in the browser, i.e. if the window's width is <= 500px. If the condition is met, the apply
callback (if it has been defined) is called. If the apply
callback was called, the system makes a note of this (this will become clear why in a bit).
Additionally, upon registering a new responder, an event listener is attached which listens for changes in applicability to the specified media query. To further the example above, if the browser's window width is less than 500px at the time the responder was registered, and then it later changes such that it is larger than 500px, the unapply
callback will be called.
A few things to note about the unapply
callback:
- it is optional
- it will only ever be called if the
apply
callback has been called first, in other words:unapply
will only be called at a maximum once for each timeapply
has been called, and only of course if the conditions of its responder'squery
no longer apply. - it will never be called if the conditions specified by its responder's
query
do not change
This system is designed to work much like CSS based media queries. If a condition is met, apply something. If that something has been applied, but the condition is no longer valid, unapply that something.
Cleanup & resetting
If your wish to remove a responder object that you previously added via respondto.addResponder
, simply pass the responder object along to respondto.removeResponder
. This will remove it from the list of registered responders, remove the additional properties added to the responder after it was registered, and remove its media query event listener.
As a convenience, if you'd like to remove all of the responders you've initialized, use: respondto.reset()
.
Example
window.respondto.addResponder({
query: 'only screen and (max-width: 500px)',
apply: function () {
// e.g.
// mobileNav.show();
// desktopNav.hide();
},
unapply: function () {
// e.g.
// mobileNav.hide();
// desktopNav.show();
}
});
Support (Native)
Desktop:
- Chrome 9+
- Firefox 6+
- Internet Explorer 10+
- Safari 5.1+
Mobile:
- iOS 5.0+
- Android 4.0+
Support for older, non-compliant browsers
If you need broader support, have no fear. Thanks to Scott Jehl, Paul Irish, and Nicholas Zakas's wonderful matchMedia
and matchMedia.addListener
polyfills respondto should work everywhere CSS media queries are supported --- e.g. Internet Explorer 9.
Contribution
Test:
$ grunt test
Build:
$ grunt build
or just
$ grunt