Breakpoint Slicer

Slice media queries with ease

Breakpoint Slicer is a set of Sass mixins that makes working with mediaqueries effortless and fun.

@include at(s)          // => @media (min-width: 400px) and (max-width: 599px)
@include from(s)        // => @media (min-width: 400px)
@include to(s)          // => @media                        (max-width: 599px)
@include between(xs, l) // => @media (min-width: 200px) and (max-width: 799px)

See below how to customize breakpoints!

Status
Concept
- Enter the mixins
- Edge cases
Installation
- npm
- Yarn
Usage with default slices
- With Sass modules and @use, recommended
- With @import
Usage with custom slices
Prepending media queries with custom media types or features
- Providing one media/feature group
- Providing multiple media/feature groups
Credit
License

Status

Breakpoint Slicer v.3 is a complete rewrite.

Breakpoint Slicer had been evolving, improving its ergonomics while maintaining compatibility with old versions and supporting now obsolete practices. As a result, it ended up being a bit messy.

It's time to shed the legacy and redesign Breakpoint Slicer with simplicity and leveraging new Sass features such as modules and maps.

See CHANGELOG.md for the list of breaking changes (there are many! 🙈).

Concept

Most media query heleprs operate with breakpoints. Here they are on a scale:

 Breakpoint:   0       200px     400px     600px     800px     1000px    1200px    1400px       
               ├─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────>

Breakpoint Slicer operates with slices instead of breakpoints. A slice is a range of viewport sizes between two consequetive breakpoints.

 Breakpoint:   0       200px     400px     600px     800px     1000px    1200px    1400px       
               ├─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────>
 Slice:            xxs        xs        s         m         l         xl       xxl       xxxl

Slices make it much easier to reason about media queries. Take any viewport width, and you can say which slice it corresponds to.

Given the slices defined above, screen width of 1024px falls into the xl slice, and screen width of 1920px falls into the xxxl slice.

The goal of Breakpoint Slicer is to let you quickly apply media queries using slice names instead of px breakpoints.

Enter the mixins

Breakpoint Slicer offers four handy mixins that let you set breakpoint ranges easily: at, from, to and between:

Styles under at(m) are applied when browser window width is inside the m slice.

Styles under from(m) are applied when browser window width is inside the m slice or larger.

Styles under to(m) are applied when browser window width is inside the m slice or smaller.

Styles under between(s, l) are applied when browser window width is inside the s slice, l slice (inclusive) and any slices in between, if any.

 Breakpoint:   0       200px     400px     600px     800px     1000px    1200px    1400px       
               ├─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────>
 Slice:        ·   xxs        xs   ·    s    ·    m    ·    l    ·    xl       xxl       xxxl   
               ·                   ·         ·         ·         ·                              
               ·                   ·         ·  at(m)  ·         ·                              
               ·                   ·         ├────────┤·         ·                              
               ·                   ·         ·         ·         ·                              
               ·                   ·         · from(m) ·         ·                              
               ·                   ·         ├─────────────────────────────────────────────────>
               ·                   ·                   ·         ·                              
               ·                   ·            to(m)  ·         ·                              
               ├──────────────────────────────────────┤·         ·                              
                                   ·                             ·                              
                                   ·         between(s, l)       ·                              
                                   ├────────────────────────────┤·

Mixin incovation	Resulting media query
at(m)	(min-width: 600px) and (max-width: 799px)
from(m)	(min-width: 600px)
to(m)	(max-width: 799px)
between(s, l)	(min-width: 400px) and (max-width: 999px)

Note that each slice includes its left breakpoint but does not include its right breakpoint.

Edge cases

Note that the last slice does not have a right edge. When it is invoked, the media query will have no max-width value.

Some mixin invocations are synonomous:

 Breakpoint:   0       200px     400px     600px     800px     1000px    1200px    1400px       
               ├─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────>
 Slice:        ·   xxs   ·    xs        s         m    ·    l         xl       xxl   ·   xxxl   
               ·         ·                             ·                             ·          
               · at(xxs) ·                             ·                             ·  at(xxxl)
               ├────────┤·                             ·                             ├─────────>
               ·         ·                             ·                             ·          
               · to(xxs) ·                             ·                             · from(xxxl)
               ├────────┤·                             ·                             ├─────────>
               ·                                       ·                                        
               ·                               to(m)   ·   from(l)                              
               ├──────────────────────────────────────┤├───────────────────────────────────────>
               ·                                       ·                                        
               ·           between(xxs, m)             ·           between(l, xxxl)             
               ├──────────────────────────────────────┤├───────────────────────────────────────>

…and some become meaningless and will produce an error, preventing you from accidentally covering all viewports with a useless media query:

 Breakpoint:   0       200px     400px     600px     800px     1000px    1200px    1400px       
               ├─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────>
 Slice:        ·   xxs        xs        s         m         l         xl       xxl       xxxl   
               ·                                                                                
               ·  from(xxs)                                                                     
               ├───────────────────────────────────────────────────────────────────────────────>
               ·                                                                                
               ·                                                                      to(xxxl)  
               ├───────────────────────────────────────────────────────────────────────────────>

Installation

npm

npm install -D breakpoint-slicer

Yarn

yarn add -D breakpoint-slicer

Usage with default slices

With Sass modules and @use, recommended

@use "node_modules/breakpoint-slicer" as bs;

.foo {
  @include bp.at(s) {
    color: red;
  }
}

With @import

Use this only if your Sass version does not support Sass modules.

Import breakpoint-slicer early in your stylesheet:

@import 'breakpoint-slicer';

This will expose mixins into the global scope:

.foo {
  @include at(s) {
    color: red;
  }
}

Usage with custom slices

Breakpoint Slicer lets you define your own set of slices.

Basics

Slices are defined as a map like this:

$slices: (
  small: 0px,
  medium: 400px,
  large: 800px,
);

Keys are slice names and values are left breakpoints of each slice.

⚠ One slice must have a left breakpoint of 0px.

It is recommended that you list slices in the incremental order.

You can pass a slices map to any of the mixins, ad-hoc style:

.foo {
  @include bp.at(small, $slices: $slices) {
    color: red;
  }
}

This approach is only useful if you have to deal with more than one set of slices per Sass module/partial.

With Sass modules and @use, recommended

This is how you can override default slices at the top of your Sass module:

// config.scss

$slices: (
  small: 0px,
  medium: 400px,
  large: 800px,
);

// my-module.scss

@use "config";
@use "node_modules/breakpoint-slicer" as bs with ($slices: config.$slices);

.foo {
  @include bp.at(small) {
    color: red;
  }
}

With @import

⚠ Use this only if your Sass version does not support Sass modules.

Define $slices globally next to your breakpoint-slicer invocation:

@import 'breakpoint-slicer';

$slices: (
  small: 0px,
  medium: 400px,
  large: 800px,
);


This will make mixins use your slices definition globally, unless overridded with an argumetn:

```scss
.foo {
  @include at(medium) {
    color: red;
  }
}

.bar {
  @include at(tablet-landscape, $slices: $other-slices) {
    color: blue;
  }
}

Prepending media queries with custom media types or features

Use the $media variable in the same manner as you use $slices, as explained above.

💡 Here only the ad-hoc variant is demonstrated, but @use and global invocations are also possible.

Providing one media/feature group

If you need something simple like screen, you can do $media: screen.

If you need to use spaces, then wrap it in parens like this: $media: (screen and (orientation: portrait)).

.foo {
  @include at(s, $media: (screen and (orientation: portrait))) {
    color: red;
  }
}

produces:

@media screen and (orientation: portrait)) and (min-width: 400px) and (max-width: 599px) {
  .foo {
    color: red;
  }
}

Providing multiple media/feature groups

You can pass media types/features split with commas, e. g $media: (screen, print):

.foo {
  @include at(s, $media: (screen, print)) {
    color: red;
  }
}

The generated media query will be duplicated for each type/feature in the list:

@media screen and (min-width: 400px) and (max-width: 599px), print and (min-width: 400px) and (max-width: 599px) {
  .foo {
    color: red;
  }
}

Credit

Built by Andrey Mikhaylov (@lolmaus) and contributors.

License

MIT.

API Docs

variables

slices

$slices: (
  xxs:     0px,
  xs:    200px,
  s:     400px,
  m:     600px,
  l:     800px,
  xl:   1000px,
  xxl:  1200px,
  xxxl: 1400px,
) !default;

View source

Description

The default slices map.

Type

Map

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

media

$media: null !default;

View source

Description

A list of media types and features to be prepended to every media query generated by breakpoint-slicer. Can assume one of the following values:

null (default) — nothing is prepended
a single media query, e. g. monochrome and (orientation: portrait)
a comma-separated list of media queries, e. g. screen, print

Type

Null</code> or <code>List

Example

$media: null;

.foo {
  @include from(s) {
    color: red;
  }
}

// produces:

@media (min-width: 400px) {
  .foo {
    color: red;
  }
}

$media: monochrome and (orientation: portrait);

.foo {
  @include from(s) {
    color: red;
  }
}

// produces:

@media monochrome and (orientation: portrait) and (min-width: 400px) {
  .foo {
    color: red;
  }
}

$media: screen, print;

.foo {
  @include from(s) {
    color: red;
  }
}

// produces:

@media screen and (min-width: 400px), print and (min-width: 400px) {
  .foo {
    color: red;
  }
}

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

mixins

at

@mixin at($slice, $slices: globally defined $slices, $media: globally defined $media) { ... }

View source

Description

Wraps CSS code with a media query confined by a given slice

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$slice`	name of slice	`String`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`
`$media`	a media query to prend the result with	`Map` or `Null`	`globally defined $media`

Example

.foo {
  @include at(s) {
    color: red;
  }
}

// produces:

@media (min-width: 400px) and (max-width: 599px) {
  .foo {
    color: red;
  }
}

.foo {
  @include at(medium, $slices: (small: 0px, medium: 300px, large: 600px), $media: (screen, print)) {
    color: red;
  }
}

// produces:

@media screen and (min-width: 300px) and (max-width: 599px), print and (min-width: 300px) and (max-width: 599px) {
  .foo {
    color: red;
  }
}

Output

CSS wrapped in a media query

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

from

@mixin from($slice, $slices: globally defined $slices, $media: globally defined $media) { ... }

View source

Description

Wraps CSS code with a media query confined by a given slice and larger

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$slice`	name of slice	`String`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`
`$media`	a media query to prend the result with	`Map` or `Null`	`globally defined $media`

Example

.foo {
  @include from(s) {
    color: red;
  }
}

// produces:

@media (min-width: 400px) {
  .foo {
    color: red;
  }
}

.foo {
  @include from(medium, $slices: (small: 0px, medium: 300px, large: 600px), $media: (screen, print)) {
    color: red;
  }
}

// produces:

@media screen and (min-width: 300px), print and (min-width: 300px) {
  .foo {
    color: red;
  }
}

Output

CSS wrapped in a media query

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

to

@mixin to($slice, $slices: globally defined $slices, $media: globally defined $media) { ... }

View source

Description

Wraps CSS code with a media query confined by a given slice and smaller

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$slice`	name of slice	`String`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`
`$media`	a media query to prend the result with	`Map` or `Null`	`globally defined $media`

Example

.foo {
  @include to(s) {
    color: red;
  }
}

// produces:

@media (max-width: 599px) {
  .foo {
    color: red;
  }
}

.foo {
  @include to(medium, $slices: (small: 0px, medium: 300px, large: 600px), $media: (screen, print)) {
    color: red;
  }
}

// produces:

@media screen and (max-width: 599px), print and (max-width: 599px) {
  .foo {
    color: red;
  }
}

Output

CSS wrapped in a media query

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

between

@mixin between($slice-start, $slice-end, $slices: globally defined $slices, $media: globally defined $media) { ... }

View source

Description

Wraps CSS code with a media query confined within two slices

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$slice-start`	name of starting slice	`String`	— none
`$slice-end`	name of ending slice, inclusive	`String`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`
`$media`	a media query to prend the result with	`Map` or `Null`	`globally defined $media`

Example

.foo {
  @include between(s, l) {
    color: red;
  }
}

// produces:

@media (min-width: 400px) and (max-width: 999px) {
  .foo {
    color: red;
  }
}

.foo {
  @include between(small, medium, $slices: (small: 0px, medium: 300px, large: 600px), $media: (screen, print)) {
    color: red;
  }
}

// produces:

@media screen and (max-width: 599px), print and (max-width: 599px) {
  .foo {
    color: red;
  }
}

Output

CSS wrapped in a media query

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

query

@mixin query($query, $slices: globally defined $slices, $media: globally defined $media) { ... }

View source

Description

Wraps CSS code with a compound media query, using flexible syntax

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$query`	a comma-separated list of slices and ranges of two slices	`Map`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`
`$media`	a media query to prend the result with	`Map` or `Null`	`globally defined $media`

Example

.foo {
  @include query((s l), xxxl) {
    color: red;
  }
}

// produces:

@media (min-width: 400px) and (max-width: 999px), (min-width: 1400px) {
  .foo {
    color: red;
  }
}

.foo {
  @include query(small, $slices: (small: 0px, large: 600px), $media: (screen, print)) {
    color: red;
  }
}

// produces:

@media screen and (max-width: 599px), print and (max-width: 599px) {
  .foo {
    color: red;
  }
}

Output

CSS wrapped in a media query

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

functions

[private] map-sort-values

@function map-sort-values($map) { ... }

View source

Description

Sorts a Sass map by its values. Values must be numeric.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$map`	a map to sort	`Map`	— none

Returns

Map —

sorted map

Example

map-sort-values((a: 200, b: 0))
// => (b: 0, a: 200)

Author

Andrew Luca https://github.com/iamandrewluca

[private] is-number-px

@function is-number-px($value) { ... }

View source

Description

Checks whether given value is a number with px unit.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$value`	a value to check	`Any`	— none

Returns

Bool —

whether the value is a number with px unit

Example

is-number-px(100px) // => true
is-number-px(100em) // => false
is-number-px(100) // => false
is-number-px('text') // => false

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

[private] index-of-slice

@function index-of-slice($slice, $slices: globally defined $slices) { ... }

View source

Description

Returns the index of given slice.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$slice`	a slice to look up	`String`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`

Returns

Number —

index of the slice (1-indexed)

Example

index-of-slice(xl) // => 6
index-of-slice(large, $slices: (small: 0px, large: 600px)) // => 2

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

[private] is-first-slice

@function is-first-slice($slice, $slices: globally defined $slices) { ... }

View source

Description

Checks whether given slice is the first one in the map.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$slice`	a slice to look up	`String`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`

Returns

Bool —

whether the slice is the first

Example

is-first-slice(xxs) // => true
is-first-slice(s) // => false
is-first-slice(small, $slices: (small: 0px, large: 600px)) // => true

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

[private] is-last-slice

@function is-last-slice($slice, $slices: globally defined $slices) { ... }

View source

Description

Checks whether given slice is the last one in the map.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$slice`	a slice to look up	`String`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`

Returns

Bool —

whether the slice is the last

Example

is-last-slice(xxl) // => false
is-last-slice(xxxl) // => true
is-last-slice(small, $slices: (small: 0px, large: 600px)) // => false

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

[private] next-slice

@function next-slice($slice, $slices: globally defined $slices) { ... }

View source

Description

Returns the name of the next slice

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$slice`	a slice to look up	`String`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`

Returns

String</code> or <code>Null —

the name of the next slice, or null if given slice was the last

Example

next-slice(s) // => m
next-slice(xxxl) // => null
next-slice(small, $slices: (small: 0px, large: 600px)) // => large

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

[private] start-bp-of-slice

@function start-bp-of-slice($slice, $slices: globally defined $slices) { ... }

View source

Description

Returns the starting (normally left) breakpoint of given slice

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$slice`	a slice to look up	`String`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`

Returns

Number</code> or <code>Null —

the breakpoint, or null if the slice is the first one

Example

start-bp-of-slice(xxs) // => null
start-bp-of-slice(xs) // => 200px
start-bp-of-slice(small, $slices: (small: 0px, large: 600px)) // => null
start-bp-of-slice(large, $slices: (small: 0px, large: 600px)) // => 600px

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

[private] end-bp-of-slice

@function end-bp-of-slice($slice, $slices: globally defined $slices) { ... }

View source

Description

Returns the ending (normally right) breakpoint of given slice, which is the left breakpoint of the next slice minus 1px, or null if the slice is the last one.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$slice`	a slice to look up	`String`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`

Returns

Number</code> or <code>Null —

the breakpoint, or null if the slice is the first one

Example

end-bp-of-slice(l) // => 999px
end-bp-of-slice(xxxl) // => null
end-bp-of-slice(small, $slices: (small: 0px, large: 600px)) // => 599px
start-bp-of-slice(large, $slices: (small: 0px, large: 600px)) // => null

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

[private] query-for-slice

@function query-for-slice($slice-start, $slice-end, $slices: globally defined $slices, $media: globally defined $media) { ... }

View source

Description

Generates a media query for a given slice or a range of two slices

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$slice-start`	a slice whose left breakpoint will be used	`String` or `Null`	— none
`$slice-end`	a slice whose right breakpoint will be used	`String` or `Null`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`
`$media`	a media query to prend the result with	`Map` or `Null`	`globally defined $media`

Returns

String —

resulting media query

Example

query-for-slice(l) // => (min-width: 800px) and (max-width: 999px)
query-for-slice(null, l) // => (max-width: 999px)
query-for-slice(l, null) // => (min-width: 800px)
query-for-slice(xxxl) // => (min-width: 1400px)
query-for-slice(xxxl, null) // => (min-width: 1400px)
query-for-slice(xxs) // => (max-width: 199px)
query-for-slice(null, xxs) // => (max-width: 199px)
query-for-slice(s l) // => (min-width: 400px) and (max-width: 999px)
query-for-slice(small, $slices: (small: 0px, large: 600px)) // => (max-width: 999px)
query-for-slice(l, $media: screen) // => screen and (min-width: 800px) and (max-width: 999px)

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

[private] query-for-slices

@function query-for-slices($query, $slices: globally defined $slices, $media: globally defined $media) { ... }

View source

Description

Generates a media query for a given comma-separated list of slices and ranges of two slices

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$query`	a comma-separated list of slices and ranges of two slices	`Map`	— none
`$slices`	a map of slices to work with	`Map`	`globally defined $slices`
`$media`	a media query to prend the result with	`Map` or `Null`	`globally defined $media`

Returns

String —

resulting media query

Example

query-for-slices(l) // => (min-width: 800px) and (max-width: 999px)
query-for-slices((null l)) // => (max-width: 999px)
query-for-slices((null l), xxxl) // => (max-width: 999px), (min-width: 1400px)
query-for-slices((s l), xxxl) // => (min-width: 400px) and (max-width: 999px), (min-width: 1400px)
query-for-slices(small, $slices: (small: 0px, large: 600px)) // => (max-width: 999px)
query-for-slices(l, $media: screen) // => screen and (min-width: 800px) and (max-width: 999px)

Author

Andrey Mikhaylov (lolmaus) https://github.com/lolmaus

Breakpoint Slicer

Status

Concept

Enter the mixins

Edge cases

Installation

npm

Yarn

Usage with default slices

With Sass modules and @use, recommended

With @import

Usage with custom slices

Basics

With Sass modules and @use, recommended

With @import

Prepending media queries with custom media types or features

Providing one media/feature group

Providing multiple media/feature groups

Credit

License

API Docs

variables

Description

Type

Author

Description

Type

Example

Author

mixins

Description

Parameters

Example

Output

Author

Description

Parameters

Example

Output

Author

Description

Parameters

Example

Output

Author

Description

Parameters

Example

Output

Author

Description

Parameters

Example

Output

Author

functions

[private] map-sort-values

Description

Parameters

Returns

Example

Links

Author

[private] is-number-px

Description

Parameters

Returns

Example

Author

[private] index-of-slice

Description

Parameters

Returns

Example

Author

[private] is-first-slice

Description

Parameters

Returns

Example