Configuration

variables

layout-max-width

Since 1.0.0

$layout-max-width: 1360px !default;

Description

Layout max-width in pixels

This value defines the layout- or content width without outer gutter/offset.

Type

Number

Used by

[mixin] show-rel-grid
[mixin] show-rel-grid

layout-offset

Since 1.0.0

$layout-offset: (
  default: 15px,
) !default;

Description

Layout offset in pixels

This value defines the outer gutter, the horizontal margin or the horizontal space between the content/grid and the "page" edge.

Type

Map

Used by

[function] get-layout-max-offset
[mixin] use-layout-offset
[mixin] use-layout-offset
[mixin] show-rel-grid
[mixin] show-rel-grid
[mixin] show-rel-grid
[mixin] show-rel-grid
[mixin] show-rel-grid
[mixin] show-rel-grid

css-grid

Since 1.0.0

$css-grid: (
  default: (
    cols-num: 6,
    col-width: 40px,
    gutter-width: 12px,
    gutter-type: 'static',
  ),
) !default;

Description

CSS grid definition

This value defines the css grid for a given breakpoint. The grid is inherited by bigger/wider breakpoints unless these breakpoints have their own config ("from"). Breakpoint names must match the names used in $breakpoints.

Type

Map

Map structure

map key Name	map key Description	map key Type	map key Value
`css-grid.[my-breakpoint]`	CSS grid definition for a given breakpoint.	`Map`	`s. below`
`css-grid.[my-breakpoint].cols-num`	Number of columns (e.g. 12)	`Number`	`6`
`css-grid.[my-breakpoint].col-width`	Width of a single column in pixels. Even if the width is configured in pixels, column width will always be fluid/relative.	`Number`	`40px`
`css-grid.[my-breakpoint].gutter-width`	Gutter width in pixels. To use relative values (%) just use `gutter-type: 'fluid'`.	`Number`	`12px`
`css-grid.[my-breakpoint].gutter-type`	`'static'` – the gutter width is set in pixels `'fluid'` – gutter width is set in percent (relative to `col-width`).	`String`	`'static'`

Example

@use '@pixelherz/sassbox' with (
  $css-grid: (
      default: (
        cols-num: 6,
        col-width: 40px,
        gutter-width: 12px,
        gutter-type: 'static',
      ),
      rabbit: (
        cols-num: 9,
        col-width: 62px,
        gutter-width: 20px,
        gutter-type: 'static',
      ),
      cat: (
        cols-num: 12,
        col-width: 84px,
        gutter-width: 32px,
        gutter-type: 'fluid',
      ),
   ),
);

Used by

[mixin] use-css-grid
[mixin] use-css-grid

rel-grid-gutter-width

Since 1.0.0

$rel-grid-gutter-width: 32px !default;

Description

Relative grid: Gutter width in pixels

Relative grid is always fluid. Even if configured in pixels (static), the output definitions will be in percent (relative).

Type

Number

Used by

[function] get-rel-grid-width

rel-grid-col-width

Since 1.0.0

$rel-grid-col-width: 84px !default;

Description

Relative grid: Column width in pixels

Relative grid is always fluid. Even if configured in pixels (static), the output definitions will be in percent (relative).

Type

Number

Used by

[function] get-rel-grid-width

font-sizes

Since 1.0.0

$font-sizes: () !default;

Description

Font sizes

A list for key/value-pairs where key is the name of the typographic preset, value is the font-size in pixels.

Type

Map

Map structure

map key Name	map key Description	map key Type	map key Value
`font-sizes.[preset]`	Font size in pixels	`Number`	— none

Example

@use '@pixelherz/sassbox' with (
  $font-sizes: (
    s: 16px,
    m: 24px,
    l: 36px,
  )
);

See

[variable] line-heights
[variable] letter-spacing
[variable] vertical-spacing
[variable] fluid-type

line-heights

Since 1.0.0

$line-heights: () !default;

Description

Line heights

A list for key/value-pairs where key is the name of the typographic preset, value is the line-height in pixels.

Type

Map

Map structure

map key Name	map key Description	map key Type	map key Value
`line-heights.[preset]`	Line height in pixels	`Number`	— none

Example

@use '@pixelherz/sassbox' with (
  $line-heights: (
    s: 20px,
    m: 30px,
    l: 45px,
  )
);

See

[variable] font-sizes
[variable] letter-spacing
[variable] vertical-spacing
[variable] fluid-type

letter-spacing

Since 1.0.0

$letter-spacing: () !default;

Description

Letter spacing

A list for key/value-pairs where key is the name of the typographic preset, value is the letter-spacing in pixels.

Type

Map

Map structure

map key Name	map key Description	map key Type	map key Value
`letter-spacing.[preset]`	Letter-spacing in your preferred unit	`Number`	`0`

Example

@use '@pixelherz/sassbox' with (
  $letter-spacing: (
    s: 0.01em,
    m: 0.005em,
    l: 0,
  )
);

See

[variable] font-sizes
[variable] line-heights
[variable] vertical-spacing
[variable] fluid-type

vertical-spacing

Since 1.0.0

$vertical-spacing: () !default;

Description

Vertical spacing

A list for key/value-pairs where key is the name of the typographic preset, value is the vertical-offset in pixels. Example: Set equal to line-height for vertical space of a blank line Example: Set half of line-height for vertical space of half a blank line

Type

Map

Map structure

map key Name	map key Description	map key Type	map key Value
`vertical-spacing.[preset]`	— none	`Number`	`0`

Example

@use '@pixelherz/sassbox' with (
  $vertical-spacing: (
    s: 20px,
    m: 30px,
  )
);

See

[variable] font-sizes
[variable] line-heights
[variable] letter-spacing
[variable] fluid-type

fluid-type

Since 1.0.0

$fluid-type: () !default;

Description

Fluid type

'Fluid' font sizes are scaled down for the given responsive breakpoints

Type

Map

Map structure

map key Name	map key Description	map key Type	map key Value
`fluid-type.[preset]`	— none	`Map`	— none

Example

@use '@pixelherz/sassbox' with (
  $fluid-type: (
    l: (
      default: 'm',
      rat: 'l',
    ),
    m: (
      default: 's',
      rat: 'm',
    )
  )
);

Used by

[mixin] use-type
[mixin] use-type
[mixin] use-type

See

[variable] line-heights
[variable] letter-spacing
[variable] vertical-spacing
[variable] font-sizes

Conversion

functions

px-to-rem

Since 1.0.0

@function px-to-rem($value) { ... }

Description

Convert px to rem.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$value`	The value in pixels to be converted to `rem`	`Number`	— none

Returns

Number —

Converted value in rem

Example

Input value is interpreted as px, unit is ignored

font-size: sassbox.pxToRem(24px); // 1.5rem
font-size: sassbox.pxToRem(24); // 1.5rem

Requires

[function] strip-unit

rem-to-px

Since 1.0.0

@function rem-to-px($value) { ... }

Description

Convert rem to px

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$value`	The value in `rem` to be converted to `px`	`Number`	— none

Returns

Number —

Converted value in px

Example

Input value is interpreted as rem, unit is ignored

font-size: sassbox.remToPx(1.5rem); // 24px
font-size: sassbox.remToPx(1.5); // 24px

Requires

[function] strip-unit

strip-unit

Since 1.0.0

@function strip-unit($value) { ... }

Description

Strip unit

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$value`	Any numeric value	`Number`	— none

Returns

Number —

Unitless value

Example

sassbox.strip-unit(16cm); // 16

Used by

[function] px-to-rem
[function] rem-to-px

Layout

mixins

use-css-grid

Since 1.0.0

@mixin use-css-grid() { ... }

Description

Inject CSS grid columns

Parameters

None.

Example

// Configuration
@use '@pixelherz/sassbox' with (
  $css-grid: (
    default: (
      cols-num: 6,
      col-width: 40px,
      gutter-width: 12px,
      gutter-type: 'static',
    ),
    rabbit: (
      cols-num: 9,
      col-width: 62px,
      gutter-width: 20px,
      gutter-type: 'static',
    ),
    cat: (
      cols-num: 12,
      col-width: 84px,
      gutter-width: 32px,
      gutter-type: 'fluid',
    ),
  ),
);

// Usage
.layout {
  display: grid;
  @include sassbox.use-css-grid();
}

Output

The declarations for grid-template-columns including the media-queries according to your configuration (cmp. configuration properties $breakpoints and $css-grid). The mixin won't set display: grid which is required for a working CSS grid layout (cmp. example).

Requires

[variable] css-grid
[variable] breakpoints
[variable] breakpoints
[variable] css-grid
[variable] breakpoints
[variable] breakpoints

See

[variable] css-grid

use-layout-offset

Since 1.0.0

@mixin use-layout-offset($prop: 'margin') { ... }

Description

Apply horizontal offset

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$prop`	By default the properties `margin-left` and `margin-right` are used. Use this parameter if you prefer another property (`padding` makes sense in some cases).	`String`	`'margin'`

Example

// Configuration
@use '@pixelherz/sassbox' with (
  $layout-offset: (
    default: 20px,
    mouse: 40px,
    rabbit: 80px,
  ),
);

// Usage
.layout {
  @include sassbox.use-layout-offset($prop: 'padding');
}

Output

Applies the left/right offset for all breakpoints defined in your configuration ($layout-offset).

Requires

[variable] layout-offset
[variable] breakpoints
[variable] breakpoints
[variable] layout-offset
[variable] breakpoints
[variable] breakpoints

show-rel-grid

Since 1.0.0

@mixin show-rel-grid($class-name: show-rel-grid) { ... }

Description

Show relative grid

Display the relative grid by adding a class-name to the html element. The class-name defaults to "show-rel-grid" but can be customized.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$class-name`	A custom class-name	`String`	`show-rel-grid`

Example

Usually included once in your root stylesheet

@use '@pixelherz/sassbox';

@include sassbox.show-rel-grid($class-name: 'show-grid');

Add the class to your html element to make the grid visible

<html class="show-grid">

Output

A CSS rule to display the relative grid according to your configuration.

Requires

[function] get-layout-max-offset
[function] get-rel-grid-width
[function] get-rel-grid-width
[function] get-rel-grid-width
[function] get-layout-max-offset
[variable] layout-max-width
[variable] layout-offset
[variable] layout-offset
[variable] layout-offset
[variable] breakpoints
[variable] layout-offset
[variable] layout-offset
[variable] breakpoints
[variable] layout-offset
[variable] breakpoints
[variable] breakpoints
[variable] layout-max-width

functions

get-layout-max-offset

Since 1.0.0

@function get-layout-max-offset() { ... }

Description

Get the maximum layout offset (outer gutter, horizontal margin).

Parameters

None.

Returns

Number —

maximum value from $layout-offset

Example

// Configuration
@use '@pixelherz/sassbox' with (
  $layout-offset: (
    default: 20px,
    mouse: 40px,
    rabbit: 80px,
  ),
  $layout-max-width: 1360px,
);

// Usage
.page {
  // get-layout-max-offset() will return `80px`
  max-width: #{sassbox.$layout-max-width + (sassbox.get-layout-max-offset() * 2)}; // 1520px
}

get-rel-grid-width

Since 1.0.0

@function get-rel-grid-width($cols: 0, $gutters: 0, $base-cols: 'all', $base-gutters: 0, $base-extra: 0, $scale: 'rel') { ... }

Description

Calculates grid widths based on the given params and returns the width as absolute (px) or relative (%) value.

Note: The gutters enclosed by columns must not be declared in the $gutters parameter (e.g. param $cols: 3 returns the width of 3 cols and 2 gutters). The $gutters param is used for extra-gutter only (left/right of the cols).

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$cols`	The number of columns the width should span	`Int`	`0`
`$gutters`	The number of extra gutters the width should span	`Int`	`0`
`$base-cols`	The number of columns used as base for relative values. Use this param if the parent element is not using the grid's full layout width.	`Enum` or `Int`	`'all'`
`$base-gutters`	– The number of extra gutters to be included in the base calculation. Note: Gutters enclosed by colums (`$base-cols`) must not be declared. This param is used only for extra gutters outside the `$base-cols`.	`Int`	`0`
`$base-extra`	Accepts a px value to adjust base width (e.g. if the base does not align with the global grid).	`Int`	`0`
`$scale`	Use 'rel' to return a relative value (%) or 'abs' to return an absolute value (px).	`Enum`	`'rel'`

Returns

Number —

relative width in %

Example

// Configuration
@use '@pixelherz/sassbox' with (
  $layout-max-width: 1360px,
  $rel-grid-gutter-width: 32px,
  $rel-grid-col-width: 84px,
  $layout-offset: (
    default: 15px,
    mouse: 30px,
    rabbit: 60px,
  ),
);

// Usage: 3 column layout
.col {
  width: sassbox.get-rel-grid-width($cols: 4);
  margin-right: sassbox.get-rel-grid-width($gutters: 1);
  &:nth-of-type(3n + 0) {
    margin-right: 0;
  }
}

Requires

[variable] rel-grid-col-width
[variable] rel-grid-gutter-width

Used by

[mixin] show-rel-grid
[mixin] show-rel-grid
[mixin] show-rel-grid

Miscellaneous

mixins

normalize

Since 1.0.0

@mixin normalize() { ... }

Description

Normalize

Reset, normalize or unify browser rendering. Use box-sizing: border-box globally.

Parameters

None.

Example

Usually included once in your root stylesheet

@include sassbox.normalize();

For older or 3rd party components you can still reset box-sizing to content-box

.some-module { box-sizing: content-box; }

Output

A bunch of CSS rules to unify browser rendering.

reset-button

Since 1.0.0

@mixin reset-button() { ... }

Description

Removes the browser-default button styles from button elements. Does not change padding.

Parameters

None.

Example

@use '@pixelherz/sassbox';

.action-button {
  @include sassbox.reset-button();
}

Output

CSS definitions required to eliminate browser defaults like appearance, border etc.

offset-text

Since 1.0.0

@mixin offset-text() { ... }

Description

Hides an element's content

Parameters

None.

Example

@use '@pixelherz/sassbox';

.logotype {
  // The text "Company Name" will be set off-element
  // in favor of the background image
  @include sassbox.offset-text();
  background-image: url('logotype.svg');
}

Output

CSS definitions to off-set and hide the content of the element

truncate-text

Since 1.1.0

@mixin truncate-text() { ... }

Description

Forces text to be rendered on a single line (prevent line-break). If the text exceeds the element width, it is truncated using ellipsis (…).

Parameters

None.

Example

@use '@pixelherz/sassbox';

.single-line {
  @include sassbox.truncate-text();
}

Output

CSS definitions to prevent line-break and hide/truncate overflow.

Typography

mixins

use-type

Since 1.0.0

@mixin use-type($size: 'm', $set-line-height: true, $set-vertical-offset: false) { ... }

Description

Allows usage of global typographic presets instead of definitions spread accross your project. Supports responsive presets (checkout configuration property $fluid-type in the example below).

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$size`	The key for the requested font size	`Enum`	`'m'`
`$set-line-height`	Set false to exclude 'line-height'	`Bool`	`true`
`$set-vertical-offset`	Set true to include 'margin-top' and 'margin-bottom'	`Bool`	`false`

Example

// Configuration
@use '@pixelherz/sassbox' with (
  $breakpoints: (
    rat: 768px,
  ),
  $font-sizes: (
    s: 16px,
    m: 24px,
    l: 36px,
  ),
  $line-heights: (
    s: 20px,
    m: 30px,
    l: 45px,
  ),
  $letter-spacing: (
    s: 0.01em,
    m: 0.005em,
    l: 0,
  ),
  $vertical-spacing: (
    s: 20px,
    m: 30px,
    l: 45px,
  ),
  $fluid-type: (
    l: (
      default: 'm',
      rat: 'l',
    ),
    m: (
      default: 's',
      rat: 'm',
    ),
  ),
);

// Usage
.title {
  @include sassbox.use-type('l');
}
.paragraph {
  @include sassbox.use-type('m', $set-vertical-offset: true);
}

Requires

[variable] fluid-type
[variable] fluid-type
[variable] breakpoints
[variable] breakpoints
[variable] fluid-type
[variable] breakpoints
[variable] breakpoints

Media Queries (sass-mq)

variables

breakpoints

$breakpoints: (
  mobile: 320px,
  tablet: 740px,
  desktop: 980px,
  wide: 1300px,
) !default;

Description

Breakpoint list

Name your breakpoints in a way that creates a ubiquitous language across team members. It will improve communication between stakeholders, designers, developers, and testers.

Type

Map

Used by

[mixin] use-css-grid
[mixin] use-css-grid
[mixin] use-css-grid
[mixin] use-css-grid
[mixin] use-layout-offset
[mixin] use-layout-offset
[mixin] use-layout-offset
[mixin] use-layout-offset
[mixin] show-rel-grid
[mixin] show-rel-grid
[mixin] show-rel-grid
[mixin] show-rel-grid
[mixin] use-type
[mixin] use-type
[mixin] use-type
[mixin] use-type
[function] get-breakpoint-width
[mixin] mq
[mixin] add-breakpoint
[mixin] show-breakpoints

show-breakpoints

$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. For example: (mobile, tablet, desktop).

Type

Map

Example

@use 'path/to/mq' with ($show-breakpoints: ('mobile', 'tablet', 'desktop'));

Used by

[mixin] show-breakpoints

media-type

$media-type: all !default;

Description

Customize the media type (for example: @media screen or @media print) By default sass-mq uses an "all" media type (@media all and …)

If you want to overried the media type, you can use this option.

Type

String

Example

@use 'path/to/mq' with ($media-type: 'screen');

Used by

[mixin] mq

functions

px2em

@function px2em($px) { ... }

Description

Convert pixels to ems

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$px`	value to convert	`Number`	— none

Returns

Number

Example

$font-size-in-ems: px2em(16px);
p { font-size: px2em(16px); }

Used by

[mixin] mq
[mixin] show-breakpoints

get-breakpoint-width

@function get-breakpoint-width($name) { ... }

Description

Get a breakpoint's width

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$name`	Name of the breakpoint. One of $breakpoints	`String`	— none

Returns

Number —

Value in pixels

Example

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

Requires

[variable] breakpoints

Used by

[mixin] mq
[mixin] show-breakpoints

[private] _quick-sort

@function _quick-sort($list) { ... }

Description

Quick sort

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$list`	List to sort	`List`	— none

Returns

List —

Sorted List

Used by

[function] _map-sort-by-value

Author

Sam Richards

[private] _map-sort-by-value

@function _map-sort-by-value($map) { ... }

Description

Sort a map by values (works with numbers only)

Parameters

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

Returns

Map —

Map sorted by value

Requires

[function] _quick-sort

Used by

[mixin] add-breakpoint

mixins

mq

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

Description

Media Query mixin

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$from`	One of $breakpoints	`String` or `Boolean`	`false`
`$until`	One of $breakpoints	`String` or `Boolean`	`false`
`$and`	Additional media query parameters	`String` or `Boolean`	`false`
`$media-type`	Media type: screen, print…	`String`	`$media-type`

Example

@use 'path/to/mq' as *;
.element {
  @include mq($from: mobile) {
    color: red;
  }
  @include mq($until: tablet) {
    color: blue;
  }
  @include mq(mobile, tablet) {
    color: green;
  }
  @include mq($from: tablet, $and: '(orientation: landscape)') {
    color: teal;
  }
  @include mq(950px) {
    color: hotpink;
  }
  @include mq(tablet, $media-type: screen) {
    color: hotpink;
  }
  // Advanced use:
  $my-breakpoints: (L: 900px, XL: 1200px);
  @include mq(L, $breakpoints: $my-breakpoints) {
    color: hotpink;
  }
}

Requires

[variable] media-type
[variable] breakpoints
[function] px2em
[function] get-breakpoint-width

Used by

[mixin] show-breakpoints

add-breakpoint

@mixin add-breakpoint($name, $width) { ... }

Description

Add a breakpoint

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$name`	Name of the breakpoint	`String`	— none
`$width`	Width of the breakpoint	`Number`	— none

Example

@include add-breakpoint(tvscreen, 1920px);
@include mq(tvscreen) {}

Requires

[function] _map-sort-by-value
[variable] breakpoints

show-breakpoints

@mixin show-breakpoints($show-breakpoints: $show-breakpoints, $breakpoints: $breakpoints) { ... }

Description

Show the active breakpoint in the top right corner of the viewport

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$show-breakpoints`	List of breakpoints to show in the top right corner	`List`	`$show-breakpoints`
`$breakpoints`	Breakpoint names and sizes	`Map`	`$breakpoints`

Example

// Show breakpoints using global settings
@include show-breakpoints;

// Show breakpoints using custom settings
@include show-breakpoints((L, XL), (S: 300px, L: 800px, XL: 1200px));

Requires

[mixin] mq
[function] get-breakpoint-width
[function] px2em
[variable] breakpoints
[variable] show-breakpoints