Simple, elegant and maintainable media queries in Sass

Fork me on GitHub

What is it?

include-media is a Sass library for writing CSS media queries in an easy and maintainable way, using a natural and simplistic syntax.

Why another library?

I spent quite some time experimenting with different libraries and mixins available out there, but eventually all of them failed to do everything I needed in an elegant way. Some of them wouldn't let me mix set breakpoints with case-specific values, others wouldn't properly handle the CSS OR operator and most of them had a syntax that I found complicated and unnatural.

include-media was the result of that experience and it includes all the features I wish I had found before, whilst maintaining a simplistic and natural syntax.

I wrote an article on CSS-Tricks about this experience, where I explain in detail the problems I found with each of the solutions I experimented with. I also wrote on David Walsh's blog about the implementation details of include-media.


Flexible declaration of breakpoints

The library comes with a list of default breakpoints: phone, tablet and desktop. If you want to change them or add more, you can simply re-declare $breakpoints using the Sass map syntax.

Because they're completely dynamic, you can adopt whatever naming convention you want for the breakpoints. Not a fan of using device names? Not a problem.

On-the-fly breakpoints

Some elements require additional rules on intermediate breakpoints, so you can create media queries that use both global breakpoints and case-specific values, specified in the units of your preference.

Smart support for media types

Media types and static expressions are optional and automatically deferred. The list of media types can be modified by declaring $media-expressions.

Expressions containing logical disjunctions, such as Chris Coyier's retina declaration, are correctly handled, even when combined with other media types or breakpoints.

Support for different units

Life isn't just about pixels. Fancy writing your media queries using em or rem units? We've got you covered.

Expression aliases

You can create aliases for expressions that you find yourself reusing a lot, no matter how complex they are (watch out for the three dots next to the variable name in the mixin call).

Height-based media queries

All expressions result in a min-width expression by default, but you can explicitly use any breakpoint with min-height instead

Context-specific breakpoints and expressions

If a component has a set of breakpoints or media expressions that aren't shared with the rest of the application, you can set them to exist only within the scope of the component


include-media is just one SCSS file that you can import into your project and start using right away.

You can download the file manually, install via npm with npm install include-media or via Yarn with yarn add include-media.

Finally, import the file dist/_include-media.scss into your project.


Documentation generated with SassDoc is available here.

The authors

Eduardo Bouças

Software engineer with a crush on the web. Created Staticman, SpeedTracker and a bunch of other stuff. He blogs, tweets, and sleeps.

Hugo Giraudel

CSS goblin. Sass hacker. Margin psycho. Author of Sass Guidelines, SassDoc, Sass Compatibility, Browserhacks and a lot of Sass stuff.