Susy: Web Layout Toolkit

Lightweight & Flexible

With the advent of flexbox and the CSS Grid module, there are fewer and fewer reasons to use a grid library like Susy – and that’s wonderful! Grid libraries were always a temporary fix, waiting for the browser to take over. Still, not everyone can play with the latest specs, and there will always be edge-cases that require manual grid-math.

Susy3 is trimmed down to the most basic features: a lightweight library of functions that can be used along with float, or flexbox or any other CSS – anywhere, any time.

npm install susy

Susy is also available in the CodeKit editor, with 10% of your purchase going to Black Girls Code when you follow the link from our site.

Getting Started

All Susy3 API functions draw on the same shorthand syntax, which consists of two parts, seperated by the word of. The first part describes a grid-span width, location (if needed), and spread (in any order):

// <width> at <location> <spread>
$span: span(2);
$span-spread: span(3 wide);

// location is only needed with asymmetrical grids
$span-location-spread: span(3 at 2 narrow);

The second half describes the grid-context columns, container-spread, and gutters in any order:

// of <columns> <container-spread> set-gutters <gutters>
$of-columns: of 6;
$of-columns-spread: of 12 wide;
$of-columns-gutters: of 12 set-gutters 2em;

There are two primary functions, span and gutter, which can be used anywhere you need to calculate grid math.

• span accepts the full shorthand syntax
• gutter only uses the second half (with or without of)

.float {
  width: span(3);
  margin-right: gutter();
}

.flexbox {
  flex: 1 1 span(3);
  padding: 0 gutter() / 2;
}

.push-3 {
  margin-left: span(3 wide);
}

Except for span-width and location, all of those settings have global defaults, which can be set in the $susy configuration map:

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

Note that the columns setting no longer accepts a single number (e.g. 12) to represent 12 equal columns. Instead, we’ve borrowed syntax from the official CSS Grid module, requiring a list of column widths, with the susy-repeat function to help when your list is repetative.

You can also pass in new configurations to a function on-the-fly:

$large-screens: (
  'columns': susy-repeat(12, 4em),
  'gutters': 1em,
);

nav {
  @media (min-width: 40em) {
    width: span(3 wide, $large-screens);
  }
}

You can also mix-and match non-comparable static and fluid units in your grid, and Susy will output a calc() value to make the math work.

// 120px 1 1 1 1 12em
$columns: 120px susy-repeat(4) 12em;
$calc: span(first 3 of $columns);

For more details, check out our introduction to spread, and full reference documentation.

Read the (Susy2) Book!