@littlemissrobot/sass-breakpoints

Little Miss Robot - Sass breakpoints

This repository contains logic and functionality to define and insert breakpoint based media queries through the use of a configuration.

This package does not contain or generate any CSS. It simply provides a system with @function and @mixin statement to manage breakpoints. It is part of the @littlemissrobot/sass-system package.

IMPORTANT

This library makes use of Dart Sass, which is the primary implementation of Sass. Make sure that your Sass compiler is making use of Dart Sass.

This means that if you are using a task manager (like Gulp) or a module bundler (like Webpack), you must indicate which compiler it should use for compiling Sass to CSS.

Furthermore, this library makes heavy use of Sass modules: @use. Therefore we recommend importing and using this library with the @use statement.

Install

# As a dependency
$ npm install @littlemissrobot/sass-breakpoints
# As a dev-dependency
$ npm install --save-dev @littlemissrobot/sass-breakpoints

Usage

1. Import the library from the node_modules folder:

@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-breakpoints" as _breakpoints;

1. Pass the configuration to the dependencies and the library:

// Dependency
@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing" as _spacing with (
    $base-font-size: 16px
);

// Library
@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-breakpoints" as _breakpoints with (
    $viewports: (
        viewport-3: 360px,
        viewport-4: 480px,
        viewport-7: 720px,
        viewport-9: 992px,
        viewport-12: 1200px
    )
);

1. Functionality of the library is now available through the namespace _breakpoints.

Concept

The main focus of this library is to create consistent usage of breakpoints. Each breakpoint should have a name and a width in pixels when it should get triggered.

Naming the breakpoints can be contextual like mobile, tablet, desktop. But this limits the amount of breakpoints we can create. Here we try avoiding using $desktop-small, $desktop-small-x, ... because these are difficult to maintain.

We recommend naming breakpoints after the hundreth they belong too. For example:

• viewport-1: 110px
• viewport-1: 120px
• viewport-2: 240px
• viewport-3: 360px
• viewport-4: 480px
• viewport-7: 720px

We recommend staying with just one value every hundreth. This is done to avoid very small gaps and inconsistencies.

The eventual breakpoint is placed in converted and placed in em. This is done because this is the only value consistent in every browser

Configuration

As a dependency, @littlemissrobot/sass-spacing, is used to calculate the breakpoint value in em.

// Dependency
@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing" as _spacing with (
    $base-font-size: 16px
);

// Library
@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-breakpoints" as _breakpoints with (
    $viewports: (
        viewport-3: 360px,
        viewport-4: 480px,
        viewport-7: 720px,
        viewport-9: 992px,
        viewport-12: 1200px
    )
);

$viewports

• unit for each value: px
• default:

$viewports: (
    viewport-0: 0px,
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px,
);

• required: true

The $viewports is a sass map where every key is the name of the viewport name and the value is its width when it should get triggered.

Mixins

at($value)

Apply a breakpoint, to every element and prop above the given minimum width of the breakpoint.

Parameters:

• $value: the minimum width, when below this width, the styling is not applied. The value can either be:

  • A number in pixels.
  • A string, which is the name of the breakpoint defined in the config.

@use "@littlemissrobot/sass-breakpoints" as _breakpoints with (
    $viewports: (
        viewport-7: 720px
    )
);

body {

    // Name of the breakpoint
    @include _breakpoints.at("viewport-7") {
        background-color: blue;
    }

    // Number in pixels
    @include _breakpoints.at(720px) {
        background-color: blue;
    }
}

// Name of the breakpoint
@include _breakpoints.at("viewport-7") {

    body {
        background-color: blue;
    }
}

// Number in pixels
@include _breakpoints.at(720px) {

    body {
        background-color: blue;
    }
}

to($value)

Apply a breakpoint, to every element and prop below the given maximum width of the breakpoint.

Parameters:

• $value: the maximum width, when above this width, the styling is not applied. The value can either be:

  • A number in pixels.
  • A string, which is the name of the breakpoint defined in the config.

@use "@littlemissrobot/sass-breakpoints" as _breakpoints with (
    $viewports: (
        viewport-7: 720px
    )
);

body {

    // Name of the breakpoint
    @include _breakpoints.to("viewport-7") {
        background-color: blue;
    }

    // Number in pixels
    @include _breakpoints.to(720px) {
        background-color: blue;
    }
}

// Name of the breakpoint
@include _breakpoints.to("viewport-7") {

    body {
        background-color: blue;
    }
}

// Number in pixels
@include _breakpoints.to(720px) {

    body {
        background-color: blue;
    }
}

between($min, $max)

Apply a breakpoint, to every element and prop between the given minimum and maximum width of the breakpoint.

Parameters:

• $min: the minimum width, when below this width, the styling is not applied. The value can either be:

  • A number in pixels.
  • A string, which is the name of the breakpoint defined in the config.

• $max: the maximum width, when above this width, the styling is not applied. The value can either be:

  • A number in pixels.
  • A string, which is the name of the breakpoint defined in the config.

@use "@littlemissrobot/sass-breakpoints" as _breakpoints with (
    $viewports: (
        viewport-7: 720px,
        viewport-9: 992px
    )
);

body {

    // Name of the breakpoint
    @include _breakpoints.between("viewport-7", "viewport-9") {
        background-color: blue;
    }

    // Number in pixels
    @include _breakpoints.between(720px, 992px) {
        background-color: blue;
    }
}

// Name of the breakpoint
@include _breakpoints.between("viewport-7", "viewport-9") {

    body {
        background-color: blue;
    }
}

// Number in pixels
@include _breakpoints.between(720px, 992px) {

    body {
        background-color: blue;
    }
}

suffixicate($at, $to)

Create a class that is suffixed with one of the viewports defined in the $viewports variable. This declaration will apply styles until a breakpoint is reached.

Parameters:

• $at: A list of names from $viewports variable to apply the class declaration to. This declaration will be applied if the viewport is above the breakpoint.

• $at: A list of names from $viewports variable to apply the class declaration to. This declaration will be applied if the viewport is below the breakpoint.

@use "@littlemissrobot/sass-breakpoints" as _breakpoints with (
    $viewports: (
		viewport-4: 480px,
        viewport-7: 720px,
		viewport-9: 992px,
		viewport-12: 1200px
    )
);

.u-hide {

	@include _breakpoints.suffixicate(
		$at: (viewport-7, viewport-9),
		$to: (viewport-4, viewport-12)
	) {
		display: none !important;
	}
}

The example above will generate:

• u-hide@at:viewport-7
• u-hide@at:viewport-9
• u-hide@to:viewport-4
• u-hide@to:viewport-12