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 columnssusy-repeat(6, 120px)
will create 6 equal120px
-wide columns120px susy-repeat(4) 120px
will create 6 columns, the first and last are120px
, while the middle 4 are equal fractions of the remainder. Susy will outputcalc()
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]
@function susy-settings()
@function susy-get()
$susy (Map)
$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 usingcalc()
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. Anarrow
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
// 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',
);
// 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',
);
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
// 12 column grid, with 5em columns
$susy: (
columns: susy-repeat(12, 5em),
);
// asymmetrical 5-column grid
$susy: (
columns: 20px susy-repeat(3, 100px) 20px,
);
/* result: #{susy-get('columns')} */
/* 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
@each $key, $value in susy-settings() {
/* #{$key}: #{$value} */
}
/* columns: 1 1 1 1 */
/* gutters: 0.25 */
/* spread: narrow */
/* container-spread: narrow */
$local: ('columns': 1 2 3 5 8);
@each $key, $value in susy-settings($local) {
/* #{$key}: #{$value} */
}
/* columns: 1 2 3 5 8 */
/* gutters: 0.25 */
/* spread: narrow */
/* container-spread: narrow */
@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
/* columns: #{susy-get('columns')} */
/* gutters: #{susy-get('gutters')} */
/* columns: 1 1 1 1 */
/* gutters: 0.25 */