Susy3 API Functions

These three functions form the core of Susy’s layout-building grid API.

Use span() and gutter() to return any grid-width, and apply the results wherever you need them: CSS width, margin, padding, flex-basis, transform, etc.
For asymmetrical-fluid grids, slice() can help manage your nesting context.

All three functions come with an unprefixed alias by default, using the susy import. Import the susy-prefix partial instead, if you only only want prefixed versions of the API.

This is a thin syntax-sugar shell around the “Su” core-math functions: su-span, su-gutter, and su-slice. If you prefer the more constrained syntax of the math engine, you are welcome to use those functions instead.

Shorthand

All functions draw on the same shorthand syntax in two parts, seperated by the word of.

Span Syntax: `<width>` [`<location>` `<spread>`]

The first part describes the span width, location, and spread in any order. Only the width is required:

span(2) will return the width of 2 columns.
span(3 wide) will return 3-columns, with an additional gutter.
location is only needed with asymmetrical grids, where span(3 at 2) will return the width of specific columns on the grid. Since these are functions, they will not handle placement for you.

Context Syntax: `[of <columns> <container-spread> <gutters>]`

The second half of Susy’s shorthand describes the grid-context – available columns, container-spread, and optional gutter override – in any order. All of these settings have globally-defined defaults:

span(2 of 6) will set the context to a slice of 6 columns from the global grid. More details below.
span(2 of 12 wide) changes the container-spread as well as the column-context.
span(2 of 12 set-gutters 0.5em) will override the global gutters setting for this one calculation.

A single unitless number for columns will be treated as a slice of the parent grid. On a grid with columns: susy-repeat(12, 120px), the shorthand of 4 will use the parent 120px column-width. You can also be more explicit, and say of susy-repeat(4, 100px). If you are using asymmetrical grids, like columns: (1 1 2 3 5 8), Susy can’t slice it for you without knowing which columns you want. The slice function accepts exactly the same syntax as span, but returns a list of columns rather than a width. Use it in your context like of slice(first 3).

@function susy-span()

aliased as span()

This is the primary function in Susy — used to return the width of a span across one or more columns, and any relevant gutters along the way. With the default settings, span(3) will return the width of 3 columns, and the 2 intermediate gutters. This can be used to set the width property of grid elements, or margin and padding to push, pull, and pad your elements.

This is a thin syntax-sugar shell around the core-math su-span() function.
The un-prefixed alias span() is available by default.

Parameters & Return

$span: (list)

Shorthand expression to define the width of the span, optionally containing:

a count, length, or column-list span.
at $n, first, or last location on asymmetrical grids, where at 1 == first, and last will calculate the proper location based on columns and span.
narrow, wide, or wider for optionally spreading across adjacent gutters.
of $n <spread> for available grid columns and spread of the container. Span counts like of 6 are valid in the context of symmetrical grids, where Susy can safely infer a slice of the parent columns.
and set-gutters $n to override global gutter settings.

$config: () (map)

Optional map of Susy grid configuration settings. See $susy documentation for details.

@return (length)

Calculated length value, using the units given, or converting to % for fraction-based grids, or a full calc function when units/fractions are not comparable outside the browser.

Examples

scss span half the grid

.foo {
  // the result is a bit under 50% to account for gutters
  width: susy-span(6 of 12);
}

css compiled

.foo {
  width: 49.15254%;
}

scss span a specific segment of asymmetrical grid

.foo {
  width: susy-span(3 at 3 of (1 2 3 5 8));
}

css compiled

.foo {
  width: 82.5%;
}

Requires

@function susy-compile()

@function su-call()

@function _susy-error() [private]

Used By

@function span()

@function susy-svg-grid()

@function _susy-svg-column-position() [private]

@function susy-gutter()

aliased as gutter()

The gutter function returns the width of a single gutter on your grid, to be applied where you see fit – on margins, padding, transform, or element width.

This is a thin syntax-sugar shell around the core-math su-gutter() function.
The un-prefixed alias gutter() is available by default.

Parameters & Return

$context: null (list | number)

Optional context for nested gutters, including shorthand for columns, gutters, and container-spread (additional shorthand will be ignored)

$config: () (map)

Optional map of Susy grid configuration settings. See $susy documentation for details.

@return (length)

Width of a gutter as % of current context, or in the units defined by column-width when available

Examples

scss add gutters before or after an element

.floats {
  float: left;
  width: span(3 of 6);
  margin-left: gutter(of 6);
}

css compiled

.floats {
  float: left;
  width: 48.27586%;
  margin-left: 3.44828%;
}

scss add gutters to padding

.flexbox {
  flex: 1 1 span(3 wide of 6 wide);
  padding: gutter(of 6) / 2;
}

css compiled

.flexbox {
  flex: 1 1 50%;
  padding: 1.72414%;
}

Requires

@function susy-compile()

@function su-call()

Used By

@function gutter()

@function susy-slice()

aliased as slice()

Working with asymmetrical grids (un-equal column widths) can be challenging – expecially when they involve fluid/fractional elements. Describing a context of (15em 6em 6em 6em 15em) is a lot to put inside the span or gutter function shorthand. This slice function returns a sub-slice of asymmetrical columns to use for a nested context. slice(3 at 2) will give you a subset of the global grid, spanning 3 columns, starting with the second.

This is a thin syntax-sugar shell around the core-math su-slice() function.
The un-prefixed alias slice() is available by default.

Parameters & Return

$span: (list)

Shorthand expression to define the subset span, optionally containing:

at $n, first, or last location on asymmetrical grids;
of $n <spread> for available grid columns and spread of the container
- Span-counts like of 6 are only valid in the context of symmetrical grids
- Valid spreads include narrow, wide, or wider

$config: () (map)

Optional map of Susy grid configuration settings. See $susy documentation for details.

@return (list)

Subset list of columns for use for a nested context

Example

scss Return a nested segment of asymmetrical grid

$context: susy-slice(3 at 3 of (1 2 3 5 8));
/* $context: #{$context}; */

css compiled

/* $context: 3 5 8; */

Requires

@function susy-compile()

@function su-call()

Used By

@function slice()

Building Grids

The web has come a long way since the days of double-margin-hacks and inconsistent subpixel rounding. In addition to floats and tables, we can now use much more powerful tools, like flexbox and CSS grid, to build more interesting and responsive layouts.

With Susy3, we hope you’ll start moving in that direction. You can still build classic 12-column Grid Systems, and we’ll help you get there, but Susy3 is primarily designed for a grid-math-on-demand approach to layout: applying our functions only where you really need grid math. Read the intro article by OddBird for more details.

Examples

scss floats

.float {
  width: span(3);
  margin-right: gutter();
}

css compiled

.float {
  width: 73.68421%;
  margin-right: 5.26316%;
}

scss flexbox

.flexbox {
  flex: 1 1 span(3);
  // half a gutter on either side…
  padding: 0 gutter() / 2;
}

css compiled

.flexbox {
  flex: 1 1 73.68421%;
  padding: 0 2.63158%;
}

scss pushing and pulling

.push-3 {
  margin-left: span(3 wide);
}

.pull-3 {
  margin-left: 0 - span(3 wide);
}

css compiled

.push-3 {
  margin-left: 78.94737%;
}

.pull-3 {
  margin-left: -78.94737%;
}

scss building an attribute system

// markup example: <div data-span="last 3"></div>
[data-span] {
  float: left;

  &:not([data-span*='last']) {
    margin-right: gutter();
  }
}

@for $span from 1 through length(susy-get('columns')) {
  [data-span*='#{$span}'] {
    width: span($span);
  }
}

css compiled

[data-span] {
  float: left;
}

[data-span]:not([data-span*='last']) {
  margin-right: 5.26316%;
}

[data-span*='1'] {
  width: 21.05263%;
}

[data-span*='2'] {
  width: 47.36842%;
}

[data-span*='3'] {
  width: 73.68421%;
}

[data-span*='4'] {
  width: 100%;
}

Susy3 API Functions

Related

@function susy-span()

@function susy-gutter()

@function susy-slice()

@function su-span()

@function su-gutter()

@function su-slice()

Shorthand

Span Syntax: <width> [<location> <spread>]

Context Syntax: [of <columns> <container-spread> <gutters>]

@function susy-span()

Parameters & Return

$span: (list)

$config: () (map)

@return (length)

Examples

Related

@function su-span()

$susy

Requires

@function susy-compile()

@function su-call()

@function _susy-error() [private]

Used By

@function span()

@function susy-svg-grid()

@function _susy-svg-column-position() [private]

@function susy-gutter()

Parameters & Return

$context: null (list | number)

$config: () (map)

@return (length)

Examples

Related

@function su-gutter()

$susy

Requires

@function susy-compile()

@function su-call()

Used By

@function gutter()

@function susy-slice()

Parameters & Return

$span: (list)

$config: () (map)

@return (list)

Example

Related

@function su-slice()

$susy

Requires

@function susy-compile()

@function su-call()

Used By

@function slice()

Building Grids

Examples

Related

Article: Welcome to Susy3 [external]

Span Syntax: `<width>` [`<location>` `<spread>`]

Context Syntax: `[of <columns> <container-spread> <gutters>]`