Shorthand

All three susy-sass3 functions — span, gutter, and slice — draw on the same shorthand syntax. It lets you describe a span and its grid context in one readable expression, and only reach for the $config map when you really need it.

// span 6 of a 12-column grid
width: span(6 of 12);

// span 3 columns of an asymmetrical grid, starting at column 2
width: span(3 at 2 of (1 2 3 5 8));

// span 3 columns with an extra side gutter, static gutter override
width: span(3 wide of 6 set-gutters 1em);

Overview

The shorthand is split into two halves, separated by the word of:

syntax

Pattern:: <span> [<location> <spread>] of <columns> <container-spread> <gutters>

Within each half the order doesn’t matter — the flags (at, of, set-gutters) tell susy-sass3 how to read each value.

Span Syntax

pattern

Format:: <width> [<location>] [<spread>]

The first half describes the span. Only the width is required.

width: A unitless count of columns (span(2)), an explicit length (span(200px)), or a column list. On a symmetrical grid a count is all you need.
location: Where the span sits on the grid, used for asymmetrical grids. Give it with the at flag — span(3 at 2) — or use the first / last keywords (at 1 == first). Since these are functions, they don’t place the element for you; they only return the width of those specific columns.
spread: How many gutters to include, using the spread keywords narrow (default), wide, or wider.

span(2);            // 2 columns, gutters between them only
span(3 wide);       // 3 columns plus one extra side gutter
span(3 at 2);       // the 2nd, 3rd, and 4th columns of an asymmetrical grid
span(last 2);       // the final 2 columns

Context Syntax

pattern

Format:: of <columns> [<container-spread>] [set-gutters <gutters>]

Everything after the of flag describes the grid context. All of these have global defaults, so the context is optional.

columns: The available columns. A single unitless number is treated as a slice of the parent grid: on a grid of susy-repeat(12, 120px), of 4 reuses the parent’s 120px column width. You can be explicit with of susy-repeat(4, 100px). Asymmetrical grids can’t be sliced from a bare number — use the slice function, e.g. of slice(first 3).
container-spread: The container-spread for this context — narrow, wide, or wider.
set-gutters: Override the global gutters for this one calculation, e.g. set-gutters 0.5em.

span(2 of 6);                  // slice of 6 columns from the global grid
span(2 of 12 wide);            // 12-column context, wide container-spread
span(2 of 12 set-gutters 0.5em); // override the gutter for this call only

Config Maps

Anywhere you’d use shorthand, you can instead pass a settings map as the second $config argument. This is handy when you keep several grids in variables:

$wide-grid: (
  'columns': susy-repeat(12),
  'gutters': 0.5,
);

.banner { width: span(8, $wide-grid); }

The map and the shorthand can also be combined — the shorthand overrides matching keys in the map:

.banner { width: span(8 wide, $wide-grid); }