Media Queries with superpowers ![Build Status](https://api.travis-ci.org/sass-mq/sass-mq.svg?branch=master)
![](https://avatars3.githubusercontent.com/u/9341289?v=3&s=300)
mq()
is a Sass mixin that helps you compose media queries in an elegant
way.
Here is a very basic example:
$mq-breakpoints: (
mobile: 320px,
tablet: 740px,
desktop: 980px,
wide: 1300px
);
@import 'mq';
.foo {
@include mq($from: mobile, $until: tablet) {
background: red;
}
@include mq($from: tablet) {
background: green;
}
}
Compiles to:
@media (min-width: 20em) and (max-width: 46.24em) {
.foo {
background: red;
}
}
@media (min-width: 46.25em) {
.foo {
background: green;
}
}
Sass MQ was crafted in-house at the Guardian. Today, many more companies and developers are using it in their projects: see who uses Sass MQ.
How to use it
Immediately play with it on SassMeister: @import 'mq';
.
OR:
-
Install with Bower: bower install sass-mq --save
OR Install with npm: npm install sass-mq --save
it supports eyeglass
OR Install with diamond: diamond install sass-mq
OR Download _mq.scss to your Sass project.
-
Import the partial in your Sass files and override default settings
with your own preferences before the file is imported:
$mq-responsive: true;
$mq-breakpoints: (
mobile: 320px,
tablet: 740px,
desktop: 980px,
wide: 1300px,
// Tweakpoints
desktopAd: 810px,
mobileLandscape: 480px
);
$mq-static-breakpoint: desktop;
$mq-show-breakpoints: (mobile, mobileLandscape, tablet, desktop, wide);
@import 'path/to/mq';
-
Play around with mq()
(see below)
Responsive mode ON (default)
mq()
takes up to three optional parameters:
$from
: inclusive min-width
boundary$until
: exclusive max-width
boundary$and
: additional custom directives
Note that $until
as a keyword is a hard limit i.e. it's breakpoint - 1.
.responsive {
@include mq($from: mobile) {
color: red;
}
@include mq($until: tablet) {
color: blue;
}
@include mq($until: tablet, $and: '(orientation: landscape)') {
color: hotpink;
}
@include mq(tablet, desktop) {
color: green;
}
}
Responsive mode OFF
To enable support for browsers that do not support @media
queries,
(IE <= 8, Firefox <= 3, Opera <= 9) set $mq-responsive: false
.
Tip: create a separate stylesheet served exclusively to these browsers,
for example with conditional comments.
When @media
queries are rasterized, browsers rely on the cascade
itself. Learn more about this technique on Jake’s blog.
To avoid rasterizing styles intended for displays larger than what those
older browsers typically run on, set $mq-static-breakpoint
to match
a breakpoint from the $mq-breakpoints
list. The default is
desktop
.
The static output will only include @media
queries that start at or
span this breakpoint and which have no custom $and
directives:
$mq-responsive: false;
$mq-static-breakpoint: desktop;
.static {
@include mq($from: mobile) {
color: lawngreen;
}
@include mq(tablet, wide) {
color: seagreen;
}
@include mq($from: desktop) {
color: forestgreen;
}
@include mq($until: tablet) {
color: indianred;
}
@include mq($until: tablet, $and: '(orientation: landscape)') {
color: crimson;
}
@include mq(mobile, desktop) {
color: firebrick;
}
}
Verbose and shortand notations
Sometimes you’ll want to be extra verbose (e.g. if you’re developing a
library based on top of sass-mq), however for readability in a codebase,
the shorthand notation is recommended.
All of these examples output the exact same thing, and are here for
reference so you can use the notation that best matches your needs:
@include mq(
$from: false,
$until: desktop,
$and: false,
$media-type: $mq-media-type // defaults to 'all'
) {
.foo {}
}
@include mq(
false,
desktop,
false,
$mq-media-type
) {
.foo {}
}
@include mq(false, desktop) {
.foo {}
}
@include mq($until: desktop) {
.foo {}
}
See the detailed API documentation
Adding custom breakpoints
@include mq-add-breakpoint(tvscreen, 1920px);
.hide-on-tv {
@include mq(tvscreen) {
display: none;
}
}
Seeing the currently active breakpoint
While developing, it can be nice to always know which breakpoint is
active. To achieve this, set the $mq-show-breakpoints
variable to
be a list of the breakpoints you want to debug, ordered by width.
The name of the active breakpoint and its pixel and em values will
then be shown in the top right corner of the viewport.
![$mq-show-breakpoints](https://raw.githubusercontent.com/sass-mq/sass-mq/master/show-breakpoints.gif)
Changing media type
If you want to specify a media type, for example to output styles
for screens only, set $mq-media-type
:
SCSS
$mq-media-type: screen;
.screen-only-element {
@include mq(mobile) {
width: 300px;
}
}
CSS output
@media screen and (max-width: 19.99em) {
.screen-only-element {
width: 300px;
}
}
Running tests
npm test
Generating the documentation
Sass MQ is documented using SassDoc.
Generate the documentation locally:
sassdoc .
Generate & deploy the documentation to http://sass-mq.github.io/sass-mq/:
npm run sassdoc
Inspired By…
On Mobile-first CSS With Legacy Browser Support
Who uses Sass MQ?
Sass MQ was developed in-house at the Guardian.
These companies and projects use Sass MQ:
Looking for a more advanced sass-mq, with support for height and other niceties?
Give @mcaskill's fork of sass-mq a try.