Susy 3.0.5

Susy3 Configuration

Susy3 has 4 core settings, in a single settings map. You’ll notice a few differences from Susy2:

Columns no longer accept a single number, like 12, but use a syntax more similar to the new CSS grid-template-columns – a list of relative sizes for each column on the grid. Unitless numbers in Susy act very similar to fr units in CSS, and the susy-repeat() function (similar to the css repeat()) helps quickly establish equal-width columns.

  • susy-repeat(12) will create 12 fluid, equal-width columns
  • susy-repeat(6, 120px) will create 6 equal 120px-wide columns
  • 120px susy-repeat(4) 120px will create 6 columns, the first and last are 120px, while the middle 4 are equal fractions of the remainder. Susy will output calc() values in order to achieve this.

Gutters haven’t changed – a single fraction or explicit width – but the calc() output feature means you can now use any combination of units and fractions to create static-gutters on a fluid grid, etc.

Spread existed in the Susy2 API as a span option, and was otherwise handled behind the scenes. Now we’re giving you full control over all spread issues. You can find a more detailed explanation of spread on the blog.

You can access your global settings at any time with the susy-settings() function, or grab a single setting from the global scope with susy-get('columns'), susy-get('gutters') etc.

$susy (Map)

scss 
$susy: () !default;

The grid is defined in a single map variable, with four initial properties: columns, gutters, spread and container-spread. Anything you put in the root $susy variable map will be treated as a global project default. You can create similar configuration maps under different variable names, to override the defaults as-needed.

Since 3.0.0-beta.1:

columns setting no longer accepts numbers (e.g. 12) for symmetrical fluid grids, or the initial 12 x 120px syntax for symmetrical fixed-unit grids. Use susy-repeat(12) or susy-repeat(12, 120px) instead.

Map Properties

columns: (list)

Columns are described by a list of numbers, representing the relative width of each column. The syntax is a simplified version of CSS native grid-template-columns, expecting a list of grid-column widths. Unitless numbers create fractional fluid columns (similar to the CSS-native fr unit), while length values (united numbers) are used to define static columns. You can mix-and match units and fractions, to create a mixed grid. Susy will generate calc() values when necessary, to make all your units work together.

Use the susy-repeat($count, $value) function to more easily repetative columns, similar to the CSS-native repeat().

  • susy-repeat(8): an 8-column, symmetrical, fluid grid.
    Identical to (1 1 1 1 1 1 1 1).
  • susy-repeat(6, 8em): a 6-column, symmetrical, em-based grid.
    Identical to (8em 8em 8em 8em 8em 8em).
  • (300px susy-repeat(4) 300px): a 6-column, asymmetrical, mixed fluid/static grid using calc() output.
    Identical to (300px 1 1 1 1 300px).

NOTE that 12 is no longer a valid 12-column grid definition, and you must list all the columns individually (or by using the susy-repeat() function).

gutters: (number)

Gutters are defined as a single width, or fluid ratio, similar to the native-CSS grid-column-gap syntax. Similar to columns, gutters can use any valid CSS length unit, or unitless numbers to define a relative fraction.

  • 0.5: a fluid gutter, half the size of a single-fraction column.
  • 1em: a static gutter, 1em wide.

Mix static gutters with fluid columns, or vice versa, and Susy will generate the required calc() to make it work.

spread: narrow (string)

Spread of an element across adjacent gutters: either narrow (none), wide (one), or wider (two)

  • Both spread settings default to narrow, the most common use-case. A narrow spread only has gutters between columns (one less gutter than columns). This is how all css-native grids work, and most margin-based grid systems.
  • A wide spread includes the same number of gutters as columns, spanning across a single side-gutter. This is how most padding-based grid systems often work, and is also useful for pushing and pulling elements into place.
  • The rare wider spread includes gutters on both sides of the column-span (one more gutters than columns).

container-spread: narrow (string)

Spread of a container around adjacent gutters: either narrow (none), wide (one), or wider (two). See spread property for details.

Examples

scss default values 
// 4 symmetrical, fluid columns
// gutters are 1/4 the size of a column
// elements span 1 less gutter than columns
// containers span 1 less gutter as well
$susy: (
  'columns': susy-repeat(4),
  'gutters': 0.25,
  'spread': 'narrow',
  'container-spread': 'narrow',
);
scss inside-static gutters 
// 6 symmetrical, fluid columns…
// gutters are static, triggering calc()…
// elements span equal columns & gutters…
// containers span equal columns & gutters…
$susy: (
  'columns': susy-repeat(6),
  'gutters': 0.5em,
  'spread': 'wide',
  'container-spread': 'wide',
);

Related

Spread examples on CodePen [external]

$_susy-defaults [private]

@function susy-repeat()

Used By

@function susy-settings()

@function susy-repeat()

Similar to the repeat(<count>, <value>) function that is available in native CSS Grid templates, the susy-repeat() function helps generate repetative layouts by repeating any value a given number of times. Where Susy previously allowed 8 as a column definition for 8 equal columns, you should now use susy-repeat(8).

Parameters & Return

$count: (integer)

The number of repetitions, e.g. 12 for a 12-column grid.

$value: 1 (*)

The value to be repeated. Technically any value can be repeated here, but the function exists to repeat column-width descriptions: e.g. the default 1 for single-fraction fluid columns, 5em for a static column, or even 5em 120px if you are alternating column widths.

@return (list)

List of repeated values

Examples

scss 
// 12 column grid, with 5em columns
$susy: (
  columns: susy-repeat(12, 5em),
);
scss 
// asymmetrical 5-column grid
$susy: (
  columns: 20px susy-repeat(3, 100px) 20px,
);

/* result: #{susy-get('columns')} */
css compiled 
/* result: 20px 100px 100px 100px 20px */

Used By

@function susy-normalize-columns()

@function susy-settings()

Return a combined map of Susy settings, based on the factory defaults ($_susy-defaults), user-defined project configuration ($susy), and any local overrides required – such as a configuration map passed into a function.

Parameters & Return

$overrides…: (maps)

Optional map override of global configuration settings. See $susy above for properties.

@return (map)

Combined map of Susy configuration settings, in order of specificity: any $overrides..., then $susy project settings, and finally the $_susy-defaults

Examples

scss global settings 
@each $key, $value in susy-settings() {
  /* #{$key}: #{$value} */
}
css compiled 
/* columns: 1 1 1 1 */
/* gutters: 0.25 */
/* spread: narrow */
/* container-spread: narrow */
scss local settings 
$local: ('columns': 1 2 3 5 8);

@each $key, $value in susy-settings($local) {
  /* #{$key}: #{$value} */
}
css compiled 
/* columns: 1 2 3 5 8 */
/* gutters: 0.25 */
/* spread: narrow */
/* container-spread: narrow */

Requires

$_susy-defaults [private]

$susy (Map)

Used By

@function susy-normalize-columns()

@function susy-get()

@function susy-compile()

@function susy-get()

Return the current global value of any Susy setting

Parameters & Return

$key: (string)

Setting to retrieve from the configuration.

@return (*)

Value mapped to $key in the configuration maps, in order of specificity: $susy, then $_susy-defaults

Example

scss 
/* columns: #{susy-get('columns')} */
/* gutters: #{susy-get('gutters')} */
css compiled 
/* columns: 1 1 1 1 */
/* gutters: 0.25 */

Requires

@function susy-settings()

@function _susy-error() [private]

Used By

@function susy-normalize()

@function susy-svg-grid()