Home

Awesome

viewports.scss

_viewports.scss is a SASS microlibrary that makes it easier to manage media queries in responsive layouts. It does this by allowing you to assign specific styles to named ranges of viewports, instead of repeating @media blocks and pixel counts all over. Works both on the sass gem and libsass.

Quick demo

Yet-another github page, and about 10 seconds to pitch this before you close the tab. So here's the beef:

// Define what ranges you want and what they're called:
$VIEWPORTS_CONFIG:
    up-to  480px it-is "tiny",
    up-to  768px it-is "small",
    up-to 1024px it-is "medium",
    beyond-that  it-is "large";

// Import the library:
@import "viewports";

Then, instead of writing:

@media (min-width: 769px) and (max-width: 1024px) {
    font-size: 150%;
}

Or, the more maintainable but even longer SASS variant:

@media (min-width: #{$smallBreakpoint + 1px}) and (max-width: #{$mediumBreakpoint}) {
    font-size: 150%;
}

You can write:

@include viewports(medium) {
    font-size: 150%;
}

Which outputs the exact same media query. You can also name several ranges:

@include viewports(small medium) { /* ... */ }

Or use simple operators to specify the ranges:

@include viewports(up-to medium) { /* ... */ }

That's it! There's also an interactive demo of how the library works. During development, you can set $VIEWPORTS_DEBUG: true; to see the currently active range directly in your page (there's an example in the top-left corner of the demo).

Installation

The library is contained in a single _viewports.scss file, which is the only thing you need to include into your project.

The only dependency is either of:

Tested and works with:

Configuration

To set up your viewports, you must define the $VIEWPORTS_CONFIG variable, with a cutesy little english-like syntax, for example:

$VIEWPORTS_CONFIG:
    up-to  600px it-is "stacked",
    up-to  750px it-is "fluid-1",
    up-to 1000px it-is "fluid-2",
    beyond-that  it-is "static";

The pixel amounts (also known as breakpoints) and quoted names are yours to choose. If you want to, you can omit this and just @import "viewports". That will leave you with sensible default viewport ranges, but you really should pick ones that make sense for your project. There's a few more bits about that below.

Importing the library depends a bit on your installation method, but it's just the path that varies, for example:

Picking a range config

One simple option, as demonstrated by the above example, is to name each of your major layout modes. A common scheme in responsive layouts is to split them into:

You'll note the "fluid" range has been split into two, as it's common to shift things around a bit as your fluid layout gains more space. You can still target all "fluid" ranges with @include viewports(fluid-1 fluid-2).

Another fine option, as demonstrated by the first example, is to look at all the devices you want to target, throw them into a few categories based on their viewport sizes, and give the categories some simple names (from "tiny" to "large", for example).

Finer details

The library declares a single SASS mixin, which can be invoked in a few ways:

The interactive demo hopefully makes these quite clear.

Test suite

To make sure it generates exactly the desired CSS output and nothing else, _viewports.scss ships with a good coverage of unit tests, which you can run by going:

$ git clone git@github.com:jareware/viewports.git
$ npm install
$ npm test

Unit testing SASS is surprisingly simple; the test cases are regular SASS files under test/spec/, and look something like this:

@import "../../viewports";

/* it handles a basic "above" query */

@include viewports(above small) {
    p { color: red; }
}

/* should equal */

@media (min-width: 769px) {
    p { color: red; }
}

This file can be compiled on its own, and executing $ sass test/spec/above-1.scss produces the following CSS output:

/* it handles a basic "above" query */
@media (min-width: 769px) {
  p {
    color: red; } }
/* should equal */
@media (min-width: 769px) {
  p {
    color: red; } }

The test runner simply does this for all spec files, makes the part following /* it the name of the test case, and compares the parts separated by /* should equal */. All test cases are executed on both supported compilers: the sass gem, and libsass (through node-sass).

Releasing

  1. Run the test suite
  2. Update supported compiler versions as necessary
  3. Update the version in package.json
  4. Update the version in bower.json
  5. Push to origin master
  6. Run $ npm publish
  7. Create release on GitHub

And finally

bill

For responsive times... make it viewports time.

License

http://opensource.org/licenses/MIT

Hand-crafted with löve by @jareware / jrw.fi.