Settings

susy-sass3 has just four core settings, stored in a single $susy map: columns, gutters, spread, and container-spread.

$susy: (
  'columns': susy-repeat(4),
  'gutters': 0.25,
  'spread': 'narrow',
  'container-spread': 'narrow',
);

Anything you put in the global $susy map is treated as a project-wide default. Every function also accepts a $config map argument, so you can override any of these per-call, or keep alternate grids in their own variables.

// global default
$susy: ('columns': susy-repeat(12));

// one-off override for a single call
$sidebar: ('columns': susy-repeat(4));
.aside { width: span(2, $sidebar); }

You can also pass grid context inline through the shorthand syntax, e.g. span(2 of 6).

Global Defaults

These are the factory defaults. Override any of them by defining your own $susy map:

$susy: (
  'columns': susy-repeat(4),  // 4 equal fluid columns
  'gutters': 0.25,            // gutter is 1/4 of one column
  'spread': 'narrow',         // span gutters only between columns
  'container-spread': 'narrow',
);

Columns

Describe the columns of the grid.

setting
Key:

columns

Scope:

global, local

Options:

<list>

Default:

susy-repeat(4)

Columns are described by a list of numbers representing the relative width of each column. This mirrors the CSS-native grid-template-columns syntax:

  • Unitless numbers create fractional, fluid columns (like the CSS fr unit).

  • Length values (with units) define static columns.

  • You can mix the two, and susy-sass3 will generate calc() values as needed to make them work together.

// 8 equal fluid columns
$susy: ('columns': susy-repeat(8));

// 6 static 8em columns
$susy: ('columns': susy-repeat(6, 8em));

// asymmetrical grid — a Fibonacci-inspired layout
$susy: ('columns': (1 1 2 3 5 8));

// mixed fluid/static (300px edges, 4 fluid middle columns) -> calc()
$susy: ('columns': (300px susy-repeat(4) 300px));

Warning

Unlike Susy 2, a bare number such as 12 is no longer a valid grid definition. Use susy-repeat(12) (or list every column) instead.

Gutters

Set the size of a gutter.

setting
Key:

gutters

Scope:

global, local

Options:

<number> | <length>

Default:

0.25

A gutter is a single width or fluid ratio, similar to the CSS-native grid-column-gap. Like columns, gutters can use any valid length unit, or a unitless number for a relative fraction.

<number>

A unitless ratio relative to a single column-unit. The default 0.25 creates gutters one quarter the size of one column.

<length>

An explicit width, e.g. 1em. Mix a static gutter with fluid columns (or vice versa) and susy-sass3 will generate the required calc().

// fluid gutter, half a column wide
$susy: ('gutters': 0.5);

// static 1em gutter on a fluid grid -> calc()
$susy: ('gutters': 1em);

Spread

Control how many gutters are included in a span.

setting
Key:

spread

Scope:

global, local

Options:

narrow | wide | wider

Default:

narrow

Spread is the number of gutters a span covers relative to its column count. See Understanding Spread for a full walk-through with worked examples.

narrow

Gutters only between columns (one fewer gutter than columns). This is how CSS-native grids and most margin-based systems work, and it’s the default.

wide

The same number of gutters as columns — spanning one side gutter. Common in padding-based systems, and handy for pushing and pulling elements.

wider

Gutters on both sides of the span (one more gutter than columns).

Container Spread

The spread of the container (context) around its edge gutters.

setting
Key:

container-spread

Scope:

global, local

Options:

narrow | wide | wider

Default:

narrow

Container-spread works exactly like spread, but applies to the available columns (the context) rather than the span itself. Together, the two spread settings give you full control over the edge gutters at both ends of the calculation.

Susy Repeat

Generate repetitive column lists.

function
Format:

susy-repeat($count, $value: 1)

$count:

<integer> — number of repetitions

$value:

value to repeat (default 1)

Similar to the CSS-native repeat(), susy-repeat() repeats a value a given number of times. Where Susy 2 accepted 8 for eight equal columns, you now write susy-repeat(8).

// 12 equal fluid columns -> (1 1 1 1 1 1 1 1 1 1 1 1)
$susy: ('columns': susy-repeat(12));

// 12 static 5em columns
$susy: ('columns': susy-repeat(12, 5em));

// combine with other values
$susy: ('columns': 20px susy-repeat(3, 100px) 20px);

Susy Settings

Return the full, merged settings map.

function
Format:

susy-settings($overrides...)

$overrides:

optional override maps

susy-settings() returns the combined configuration, in order of specificity: any $overrides you pass, then your project $susy map, and finally the factory defaults.

@each $key, $value in susy-settings() {
  /* #{$key}: #{$value} */
}

Susy Get

Read a single global setting.

function
Format:

susy-get($key)

$key:

name of the setting to retrieve

/* columns: #{susy-get('columns')} */
/* gutters: #{susy-get('gutters')} */

If the key doesn’t exist, susy-get raises a susy-sass3 error.

Susy Version

Report the active susy-sass3 version.

function
Format:

susy-version($part: null)

$part:

'major' | 'minor' | 'patch' | (any other value)

With no argument, susy-version() returns the full version string (e.g. "3.1.0"). Pass 'major', 'minor', or 'patch' to get that part as a number, which is useful for version comparisons.

/* Full version: #{susy-version()} */
/* Major release: #{susy-version('major')} */