JigSass Tools Mq

NPM version Build Status Dependency Status

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

parameterNameparameterDescriptionparameterTypeparameterDefault 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

parameterNameparameterDescriptionparameterTypeparameterDefault 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,

Used by

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

parameterNameparameterDescriptionparameterTypeparameterDefault value
$breakpoint

The breakpoint name to check for.

Stringnone
$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

parameterNameparameterDescriptionparameterTypeparameterDefault value
$active-bp

The name of the length breakpoint to evaluate active breakpoints for.

Stringnone

Returns

String

A JSON-like string

Requires

Used by

[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

parameterNameparameterDescriptionparameterTypeparameterDefault value
$px

value to convert

Numbernone
$supress-warnings

Suppress warnings about converting unitless numbers into pixels.

Booleanfalse

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

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

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

Description

Get a breakpoint's width

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$name

Breakpoint to get the width of

Stringnone
$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

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 keyNameMap keyDescriptionMap keyTypeMap 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.

Mapnone
features

A map of name: rule key-value pairs, defining commonly used miscellaneous media-query features. Used when evaluating the $from and $until arguments.

Mapnone

Used by

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

Links

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

Links

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

mixins

jigsass-mq

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

Description

Generate media queries

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$from

Min-width (inclusive) in pixels, or one of $jigsass-breakpoints.lengths

String or Number or Booleanfalse
$until

Max-width (exclusive) in pixels, or one of $jigsass-breakpoints.lengths

String or Number or Booleanfalse
$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 Booleanfalse
$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

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

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

parameterNameparameterDescriptionparameterTypeparameterDefault 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.

Booleanfalse

Content

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

Requires

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

parameterNameparameterDescriptionparameterTypeparameterDefault 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.

Stringbody

Requires