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.
Features
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.
- $breakpoints: (phone: 320px, tablet: 768px, desktop: 1024px);
- /* Inclusive and exclusive operators for a finer control over the intervals */
- @include media(">phone", "<=tablet") {
- width: 50%;
- }
- /* Use ligatured operators if you fancy a slicker declaration */
- @include media("≥phone", "≤tablet") {
- line-height: 1.5;
- }
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.
- $breakpoints: (small: 320px, medium: 768px, large: 1024px);
- /* Inclusive and exclusive operators for a finer control over the intervals */
- @include media(">medium", "<=large") {
- width: 100%;
- }
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.
- @include media(">desktop", "<=1150px") {
- font-size: 4.0rem;
- }
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.
- @include media("retina2x", ">desktop") {
- width: 100%;
- }
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.
- $breakpoints: (phone: 20em, tablet: 48em, desktop: 64em);
- @include media(">tablet", "<=52em") {
- background-color: #bad;
- }
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).
- $my-weird-bp: ">=tablet", "<815px", "landscape", "retina3x";
- @include media($my-weird-bp...) {
- display: inline-block;
- }
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
- $breakpoints: (small: 320px, medium: 768px, large: 1024px);
- @include media("height>small", "height<=medium") {
- height: 50%;
- }
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-context(('custom': 678px)) {
- .my-component {
- @include media(">phone", "<=custom") {
- border-radius: 100%;
- }
- }
- }
Download
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
The authors
