JigSass Tools Mq

Easy peasy media queries. Based on Kaelig's Sass-mq, with a few minor adjustments for JigSass

Installation

Using npm (supports eyeglass):

npm i -S jigsass-tools-mq

Or download

Usage

scss/index.scss is JigSass Tools Mq's importable file.

@import 'path/to/jigsass-tools-mq/scss/index.scss'; should give you all you need.

Overriding defaults

Override default named breakpoints with your own by defining the jigsass-breakpoints variable before jigsass-mq is imported:

Breakpoint names and values can and should be redefined to fit a project design and the language used be the team working on it. However, please keep in mind that the JigSass framework depends on a 0-sized length breakpoint being defined, as it is internally used to set up default values in several places.

// The `jigsass-mq` mixin will try and resolve values from 
// the `lengths` sub-map when evaluating the `$from` and 
// `$until` arguments. When evaluating the `$misc` argument, 
// it will try and resolve values from the `features` sub-map.
$jigsass-breakpoints: (
  lengths: (
    default: 0,
    tiny: 320px,
    small: 480px,
    meduim: 600px,
    large: 1024px,
    x-large: 1280px,
  ),

  features: (
    landscape: '(orientation: landscape)',
    partrait: '(orientation: portrait)',
    hidpi: '(-webkit-min-device-pixel-ratio: 1.3),
            (min-resolution: 120dpi),
            (min-resolution: 1.3dppx)',
  ),
);

@import 'path/to/jigsass-tools-mq/scss/index.scss';

Basic usage

The jigsass-mq mixin takes optional arguments to generate min-width, max-width, media-type and miscellaneous media queries:

$from: min-width $until: max-width (exclusive, value of named breakpoint - 1) $misc: miscellaneous features, can take a list of multiple features. $media-type: A media type, i.e print, handheld, screen, etc.

.responsive {
color: red;
  @include jigsass-mq($from: small, $misc: landscape '(min-color: 8)') {
    color: pink
  }
}

Will compile to:

.responsive {
  color: red;
}

@media (min-width: 30em) and (orientation: landscape) and (min-color: 8) {
  .responsive {
    color: pink;
  }
}

The jigsass-mq mixin stores the currently active min-width breakpoint in the $jigsass-mq-active-breakpoint variable, which is available to the @content during the execution of of the mixin.

When not in the context of a media query, $jigsass-mq-active-breakpoint is set to the zero-width length breakpoint.

License: MIT

media queries

functions

jigsass-get-default-breakpoint

@function jigsass-get-default-breakpoint($breakpoints: $jigsass-breakpoints) { ... }

Description

Get the name of the zero-sized breakpoint

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$breakpoints`	The map of breakpoints to iterate over.	`Map`	`$jigsass-breakpoints`

Returns

String —

The name of the default breakpoint

jigsass-mq-sort-length-breakpoints

@function jigsass-mq-sort-length-breakpoints($bps: $jigsass-breakpoints.lengths) { ... }

Description

Sort length breakpoints by size from small to large.

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$bps`	The breakpoints to sort	`Map`	`$jigsass-breakpoints.lengths`

Returns

Map —

The sorted breakpoints

Throws

jigsass-mq-sort-length-breakpoints: Length breakpoints must resolve to numbers,

jigsass-mq-breakpoint-defined

@function jigsass-mq-breakpoint-defined($breakpoint, $breakpoints: $jigsass-breakpoints) { ... }

Description

Check if a breakpoint is defined as a named breakpoint

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$breakpoint`	The breakpoint name to check for.	`String`	—none
`$breakpoints`	The map to check for `$breakpoint` in.	`Map`	`$jigsass-breakpoints`

Returns

Boolean —

Is the breakpoint defined.

[private] _jigsass-mq-bps-to-json

@function _jigsass-mq-bps-to-json($active-bp) { ... }

Description

A helper function which generates a JSON-like string with information about length breakpoint values and which breakpoints are currently active.

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$active-bp`	The name of the length breakpoint to evaluate active breakpoints for.	`String`	—none

Returns

String —

A JSON-like string

Requires

[function] jigsass-mq-sort-length-breakpoints

Used by

[mixin] jigsass-mq-export-length-bps

[private] _jigsass-mq-px2em

@function _jigsass-mq-px2em($px, $supress-warnings: false) { ... }

Description

Convert Pixel values to ems based on the browser's default font-size.

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$px`	value to convert	`Number`	—none
`$supress-warnings`	Suppress warnings about converting unitless numbers into pixels.	`Boolean`	`false`

Returns

Number —

The converted number in ems

Throws

_jigsass-mq-px2em: Only numbers can be converted in into ems.
_jigsass-mq-px2em: Only px values can be safely converted into ems.

Used by

[mixin] jigsass-mq

[private] jigsass-mq-get-breakpoint-width

@function jigsass-mq-get-breakpoint-width($name, $breakpoints: $jigsass-breakpoints) { ... }

Description

Get a breakpoint's width

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$name`	Breakpoint to get the width of	`String`	—none
`$breakpoints`	The map to search for the breakpoint in.	`Map`	`$jigsass-breakpoints`

Returns

Number —

Value in pixels

Example

$tablet-width: jigsass-mq-get-breakpoint-width(tablet);
@media (min-width: jigsass-mq-get-breakpoint-width(desktop)) {}

Used by

[mixin] jigsass-mq

variables

jigsass-breakpoints

$jigsass-breakpoints: (
  lengths: (
    default: 0,
    tiny: 320px,
    small: 480px,
    medium: 600px,
    large: 1024px,
    x-large: 1280px,
  ),

  features: (
    landscape: '(orientation: landscape)',
    partrait: '(orientation: portrait)',
    hidpi: '(-webkit-min-device-pixel-ratio: 1.3),
            (min-resolution: 120dpi),
            (min-resolution: 1.3dppx)',
  ),
) !default;

Description

Named breakpoints

Breakpoint names and values can and should be redefined to fit a project design and the language used be the team working on it. However, please keep in mind that the JigSass framework depends on a 0-sized length breakpoint called default being defined, as it is internally used to set up default values in several places.

The jigsass-mq mixin will try and resolve values from the lengths sub-map when evaluating the $from and $until arguments. When evaluating the $misc argument, it will try and resolve values from the features sub-map.

Type

Map

Map structure

Map keyName	Map keyDescription	Map keyType	Map keyValue
`lengths`	A map of `name: width` key-value pairs, defining widths for commonly used media queries. Used when evaluating the `$from` and `$until` arguments.	`Map`	—none
`features`	A map of `name: rule` key-value pairs, defining commonly used miscellaneous media-query features. Used when evaluating the `$from` and `$until` arguments.	`Map`	—none

Used by

[mixin] jigsass-mq
[mixin] jigsass-mq-tweakpoints

jigsass-mq-responsive

$jigsass-mq-responsive: true !default;

Description

Responsive mode

Set to false to enable support for browsers that do not support @media queries, (IE <= 8, Firefox <= 3, Opera <= 9)

You could create a stylesheet served exclusively to older browsers, where @media queries are rasterized

Type

Boolean

Example

// old-ie.scss
$jigsass-mq-responsive: false;
@import 'main'; // @media queries in this file will be
                // rasterized up to $jigsass-mq-static-breakpoint
                // larger breakpoints will be ignored

Used by

[mixin] jigsass-mq

jigsass-mq-static-breakpoint

$jigsass-mq-static-breakpoint: large !default;

Description

Static breakpoint (for fixed-width layouts)

Define the breakpoint from $jigsass-breakpoints that should be used as the target width for the fixed-width layout (i.e. when $jigsass-mq-responsive is set to 'false') in an old-ie.scss

Type

String

Example

// tablet-only.scss
//
// Ignore all styles above `tablet` breakpoint,
// and fix the styles (e.g. layout) at `tablet` width
$jigsass-mq-responsive: false;
$jigsass-mq-static-breakpoint: tablet;
@import 'main'; // @media queries in this file will be rasterized up to tablet
                 // larger breakpoints will be ignored

jigsass-mq-show-breakpoints

$jigsass-mq-show-breakpoints: () !default;

Description

Show breakpoints in the top right corner

If you want to display the currently active breakpoint in the top right corner of your site during development, add the breakpoints to this list, ordered by width, e.g. (mobile, tablet, desktop).

Type

Map

jigsass-mq-media-type

$jigsass-mq-media-type: all !default;

Description

Customize the media type (e.g. @media screen or @media print) By default jigsass-mq does not restrict the media type (@media …)

Type

String

jigsass-mq-active-breakpoint

$jigsass-mq-active-breakpoint: jigsass-get-default-breakpoint();

Description

The name of the currently active min-width breakpoint

Type

String

Used by

[mixin] jigsass-mq

mixins

jigsass-mq

@mixin jigsass-mq($from: false, $until: false, $misc: false, $media-type: $jigsass-mq-media-type) { ... }

Description

Generate media queries

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$from`	Min-width (inclusive) in pixels, or one of `$jigsass-breakpoints.lengths`	`String` or `Number` or `Boolean`	`false`
`$until`	Max-width (exclusive) in pixels, or one of `$jigsass-breakpoints.lengths`	`String` or `Number` or `Boolean`	`false`
`$misc`	Miscellaneous media query parameters. One of `$jigsass-breakpoints.features` or a free-form string. Can also be a list of multiple media-query features.	`String` or `List` or `Boolean`	`false`
`$media-type`	Media type: screen, print…	`String`	`$jigsass-mq-media-type`

Content

This mixin allows extra content to be passed (through the @content directive). Role: styling rules, wrapped into a @media query when responsive mode in turned on.

Throws

jigsass-mq: #{$from} is not a length breakpoint in $jigsass-breakpoints.
jigsass-mq: #{$until} is not a length breakpoint in $jigsass-breakpoints.

Requires

[function] _jigsass-mq-px2em
[function] jigsass-mq-get-breakpoint-width
[variable] jigsass-breakpoints
[variable] jigsass-mq-responsive
[variable] jigsass-mq-active-breakpoint

Example

.element {
  @include mq($from: mobile) {
    color: red;
  }
  @include mq($until: tablet) {
    color: blue;
  }
  @include mq(mobile, tablet) {
    color: green;
  }
  @include mq($from: tablet, $misc: landscape hidpi) {
    color: teal;
  }
  @include mq(950px) {
    color: hotpink;
  }
  @include mq(tablet, $media-type: screen) {
    color: hotpink;
  }
  // Advanced use:
  @include mq(x-large:, $static-breakpoint: x-large) {
    color: hotpink;
  }
}

Used by

[mixin] jigsass-mq-export-length-bps

jigsass-mq-tweakpoints

@mixin jigsass-mq-tweakpoints($tweakpoints: (), $length-tweakpoints: (), $length-tweakpoints: (), $overwrite: false) { ... }

Description

Tweak the list of defined breakpoints within the scope of the mixin's @content

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$tweakpoints`	A map of named breakpoints to add to (or be used to overwrite) the existing breakpoints in $jigsass-breakpoints.	`Map`	`()`
`$length-tweakpoints`	A map of named lengths to add to (or be used to overwrite) the existing length-breakpoints.	`Map`	`()`
`$length-tweakpoints`	A map of named miscellaneous media-query features to add to (or be used to overwrite) the existing feature-breakpoints.	`Map`	`()`
`$overwrite`	Determines whether the tweakpoints should overwrite the existing breakpoints, or be merged into them.	`Boolean`	`false`

Content

This mixin allows extra content to be passed (through the @content directive).

Requires

[variable] jigsass-breakpoints

Example

Add a custom length breakpoint

@include jigsass-tweakpoints(('masthead-collapse': 550px)) {
  @include jigsass-mq(masthead-collapse) {
    .masthead {
      // ...
    }
  }
}

Add a custom feature breakpoint

@include jigsass-tweakpoints($feature-tweakpoints: ('8bit': ('min-color': 8))) {
  @include jigsass-mq($misc: 8bit) {
    .page--has-color {
      // ...
    }
  }
}

Temporarily overwrite existing length breakpoints

$masthead-bps: (small: 350px, medium: 500px, large: 800px);

@include jigsass-tweakpoints($masthead-bps, $overwrite: false) {
  $lengths: map-get($jigsass-breakpoints, lengths);
  @each $length in $lengths {
    @include jigsass-mq($length) {
      // ...
    }
  }
}

jigsass-mq-export-length-bps

@mixin jigsass-mq-export-length-bps($element: body) { ... }

Description

Export a JSON-like representation of defined breakpoints, and indicate if given breakpoint is active at given viewport conditions.

The exported JSON will have to following keys:

values: an object with <name>: <length> pairs for each defined length breakpoint.
from: an object with a key for each defined breakpoint, containing a nested object with from: <value> and active: <boolean> keys.
until: an object with a key for each defined breakpoint, containing a nested object with until: <value> and active: <boolean> keys.
from-until: an object with a key for each defined breakpoint, containing a nested object with from: <value>, until: <value> and active: <boolean> keys.

The mixin produces pretty heavy CSS (8.4k in default settings), but one that gets gzipped very well (8.4k -> 452b).

Parameters

parameterName parameterDescription parameterType parameterDefault value

parameterName	parameterDescription	parameterType	parameterDefault value
`$element`	The element to attach JSON data to. The JSON string will be attached to the `content` property of the `::after` psudo-element of the specified element.	`String`	`body`

$element

The element to attach JSON data to.

The JSON string will be attached to the content property of the ::after psudo-element of the specified element.

String

body

Requires

[mixin] jigsass-mq
[function] jigsass-mq-sort-length-breakpoints
[function] _jigsass-mq-bps-to-json

JigSass Tools Mq

Installation

Usage

Overriding defaults

Basic usage

media queries

functions

Description

Parameters

Returns

Description

Parameters

Returns

Throws

Used by

Description

Parameters

Returns

[private] _jigsass-mq-bps-to-json

Description

Parameters

Returns

Requires

Used by

[private] _jigsass-mq-px2em

Description

Parameters

Returns

Throws

Used by

[private] jigsass-mq-get-breakpoint-width

Description

Parameters

Returns

Example

Used by

variables

Description

Type

Map structure

Used by

Description

Type

Example

Used by

Links

Description

Type

Example

Description

Type

Description

Type

Links

Description

Type

Used by

mixins

Description

Parameters

Content

Throws

Requires

Example

Used by

Description

Parameters

Content

Requires

Example

Description

Parameters

Requires