Settings¶

Global Defaults¶

Here are all the global Susy settings with their default values:

$susy: (
  flow: ltr,
  math: fluid,
  output: float,
  gutter-position: after,
  container: auto,
  container-position: center,
  columns: 4,
  gutters: .25,
  column-width: false,
  global-box-sizing: content-box,
  last-flow: to,
  debug: (
    image: hide,
    color: rgba(#66f, .25),
    output: background,
    toggle: top right,
  ),
  use-custom: (
    background-image: true,
    background-options: false,
    box-sizing: true,
    clearfix: false,
    rem: true,
  )
);

You can set your own global defaults, or create individual layout maps to access as needed.

For global settings, create a $susy variable with any values that you need.

$susy: (
  columns: 12,
  gutters: .25,
  gutter-position: inside,
)

Layout¶

A “layout” in Susy is made up of any combination of settings. Layouts are stored as maps, but can also be written as shorthand.

// function input
$map: layout(auto 12 .25 inside fluid isolate);

//output
$map: (
  container: auto,
  columns: 12,
  gutters: .25,
  gutter-position: inside,
  math: fluid,
  output: isolate,
);

// THIS WON'T WORK
$short: 12 .25 inside;
@include layout($short fluid no-gutters);

// THIS WILL WORK
$map: layout(12 .25 inside);
@include layout($map fluid no-gutters);

$map1: 13 static;
$map2: (6em 1em) inside;
@include layout($map1 $map2);

// mixin: set a global layout
@include layout(12 1/4 inside-static);

@include with-layout(8 static) {
  // Temporary 8-column static grid...
}

// Global settings are restored...

Susy-Get¶

function

Format:	susy-get($key, $layout)
$key:	Setting name
$layout:	<layout>

You can access your layout settings at any time, using the susy-get function.

$large: layout(80em 24 1/4 inside);
$large-container: susy-get(container, $large);

To access a nested setting like debug/image, send the full path as a list for the $key argument.

$debug-image: susy-get(debug image);

If no setting is available (or no $layout is provided) susy-get falls back to the global user settings, and finally to the Susy default settings.

Flow¶

The reading direction of your document. Layout elements will stack out in the direction of flow, unless otherwise directed.

setting

Key:	flow
Scope:	global, local
Options:	rtl | ltr
Default:	ltr

ltr

Layout elements will flow from left to right.

rtl

Layout elements will flow from right to left.

Math¶

Susy can produce either relative widths (fluid percentages) or static widths (using given units).

setting

Key:	math
Scope:	global, local
Options:	fluid | static
Default:	fluid

fluid

All internal grid spans will be calculated relative to the container, and output as % values.

static

All internal grid values will be calculated as multiples of the column-width setting. If you set column-width to 4em, your grid widths will be output as em values.

Output¶

Susy can generate output using different layout techniques. Currently we have a float module, with an extension to handle isolation as well. In the future there could be flexbox, grid, and other output styles.

setting

Key:	output
Scope:	global, local
Options:	float | isolate
Default:	float

float

Floats are the most common form of layout used on the web.

isolate

Isolation is a trick developed by John Albin Wilkins to help fix sub-pixel rounding bugs in fluid, floated layouts. You can think of it like absolute positioning of floats. We find it to be very useful for spot-checking the worst rounding bugs, but we think it’s overkill as a layout technique all to itself.

Container¶

Set the max-width of the containing element.

setting

Key:	container
Scope:	global, local [container only]
Options:	<length> | auto
Default:	auto

<length>

Set any explicit length (e.g. 60em or 80%), and it will be applied directly to the container.

auto

Susy will calculate the width of your container based on the other grid settings, or fall back to 100%.

Container Position¶

Align the container relative to it’s parent element (often the viewport).

setting

Key:	container-position
Scope:	global, local [container only]
Options:	left | center | right | <length> [*2]
Default:	center

left

Holds container elements flush left, with margin-left: 0; and margin-right: auto;.

center

Centers the container, by setting both left and right margins to auto.

right

Pushes the container flush right, with margin-right: 0; and margin-left: auto;.

<length> [*2]

If one length is given, it will be applied to both side margins, to offset the container from the edges of the viewport. If two values are given, they will be used as left and right margins respectively.

Columns¶

Establish the column-count and arrangement for a grid.

setting

Key:	columns
Scope:	global, local
Options:	<number> | <list>
Default:	4

<number>

The number of columns in your layout.

<list>

For asymmetrical grids, list the size of each column relative to the other columns, where 1 is a single column-unit. (1 2) would create a 2-column grid, with the second column being twice the width of the first. For a Fibonacci-inspired grid, use (1 1 2 3 5 8 13).

Gutters¶

Set the width of a gutter relative to columns on your grid.

setting

Key:	gutters
Scope:	global, local
Options:	<ratio>
Default:	1/4

<ratio>

Gutters are established as a ratio to the size of a column. The default 1/4 setting will create gutters one quarter the size of a column. In asymmetrical grids, this is 1/4 the size of a single column-unit.

If you want to set explicit column and gutter widths, write your gutters setting as <gutter-width>/<column-width>. You can even leave the units attached.

// 70px columns, 20px gutters
$susy: (
  gutters: 20px/70px,
);

Column Width¶

Optionally set the explicit width of a column.

setting

Key:	column-width
Scope:	global, local
Options:	<length> | false/null
Default:	false

<length>

The width of one column, using any valid unit. This will be used in static layouts to calculate all grid widths, but can also be used by fluid layouts to calculate an outer maximum width for the container.

false/null

There is no need for column-width in fluid layouts unless you specifically want the container-width calculated for you.

Gutter Position¶

Set how and where gutters are added to the layout, either as padding or margins on layout elements.

setting

Key:	gutter-position
Scope:	global, local
Options:	before | after | split | inside | inside-static
Default:	after

before

Gutters are added as margin before a layout element, relative to the flow direction (left-margin for ltr, right-margin for rtl). The first gutter on each row will need to be removed.

after

Gutters are added as margin after a layout element, relative to the flow direction. The last gutter on each row will need to be removed.

split

Gutters are added as margin on both sides of a layout element, and are not removed at the edges of the grid.

inside

Gutters are added as padding on both sides of a layout element, and are not removed at the edges of the grid.

inside-static

Gutters are added as static padding on both sides of a layout element, even in a fluid layout context, and are not removed at the edges of the grid.

Global Box Sizing¶

Tell Susy what box model is being applied globally.

setting

Key:	global-box-sizing
Scope:	global
Options:	border-box | content-box
Default:	content-box

content-box

Browsers use the content-box model unless you specify otherwise.

border-box

If you are using the Paul Irish universal border-box technique (or something similar), you should change this setting to border-box. You can also use our border-box-sizing mixin, and we’ll take care of it all for you.

For more, see the MDN box-sizing documentation.

Last Flow¶

The float-direction for the last element in a row when using the float output.

setting

Key:	last-flow
Scope:	global
Options:	from | to
Default:	to

from

This is the default for all other elements in a layout. In an ltr (left-to-right) flow, the from-direction is left, and this setting would float “last” elements to the left, along with the other elements.

to

In many cases (especially with fluid grids), it can be helpful to float the last element in a row in the opposite direction.

Debug¶

Susy has a few tools to help in debugging your layout as you work. These settings help you control the debugging environment.

setting block

Key:	debug
Scope:	global, local [container only]
Options:	<map of sub-settings>

$susy: (
  debug: (
    image: show,
    color: blue,
    output: overlay,
    toggle: top right,
  ),
);

Custom Support¶

There are several common helpers that you can tell Susy to use, if you provide them yourself or through a third-party library like Compass or Bourbon.

Location¶

Reference a specific column on the grid for row edges, isolation, or asymmetrical layouts. Locations keywords don’t require the at flag.

setting

Key:	location
Scope:	local
Options:	first/alpha | last/omega | <number>
Default:	null

first
alpha

Set location to 1.

last
omega

Set the location to the final column, and any previous columns included by the relevant span.

<number>

Set the location to any column-index between 1 and the total number of available columns.

Box Sizing¶

Set a new box model on any given element.

setting

Key:	box-sizing
Scope:	local
Options:	border-box | content-box
Default:	null

border-box

Output box-sizing CSS to set the border-box model.

content-box

Output box-sizing CSS to set the content-box model.

Spread¶

Adjust how many gutters are included in a column span.

setting

Key:	spread
Scope:	local
Options:	narrow | wide | wider
Default:	various...

narrow

In most cases, column-spans include the gutters between columns. A span of 3 narrow covers the width of 3 columns, as well as 2 internal gutters. This is the default in most cases.

wide

Sometimes you need to include one side gutter in a span width. A span of 3 wide covers the width of 3 columns, and 3 gutters (2 internal, and 1 side). This is the default for several margin/padding mixins.

wider

Sometimes you need to include both side gutters in a span width. A span of 3 wider covers the width of 3 columns, and 4 gutters (2 internal, and 2 sides).

Gutter Override¶

Set an explicit one-off gutter-width on an element, or remove its gutters entirely.

setting

Key:	gutter-override
Scope:	local
Options:	no-gutters/no-gutter | <length>
Default:	null

no-gutters
no-gutter

Remove all gutter output.

<length>

Override the calculated gutter output with an explicit width.

Role¶

Mark a grid element as a nesting context for child elements.

setting

Key:	role
Scope:	local
Options:	nest
Default:	null

nest

Mark an internal grid element as a context for nested grids.