# 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.

### related

#### Article: Understanding Spread in Susy3 [external]

#### $susy

#### @function susy-settings()

#### @function susy-get()

## $susy (Map)

scss

    $susy: () !default;

### Description

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()

### Description

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()

### Description

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-get()

#### @function susy-compile()

#### @function susy-normalize-columns()

## @function susy-get()

### Description

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-svg-grid()

#### @function susy-normalize()