An OddBird Project

Susy: Web Layout Toolkit

Your design, our math

Susy is a lightweight grid-layout engine for Sass, designed to simplify and clarify responsive grid layouts without ever getting in your way. You can use Susy with floats, flexbox, tables, or any other CSS technique. You're the expert, we're just here to make your job easier.

Lightweight & Flexible

‘npm package’ ‘build status’

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
Susy3 Documentation Susy2 Documentation

I like the idea of grids-on-demand, rather than a strict framework.

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.

My experiments have left me impressed. The current state of CSS layout means that unless you like to spend a lot of time doing calculations something like Susy is really useful. The output CSS is pretty much what I’d come up with myself, which to me is the acid test for tool use.

Read the (Susy2) Book!

'Learning Susy'

Learning Susy

Zell Liew wrote a great book to get you started with Susy. You can even Get the first five chapters for free! Here are some of the things that you’ll learn:

  • How to use the Span Mixin
  • How to output the Background Grid
  • How to configure the Global Settings to your needs
  • How to do mobile-first responsive coding with Susy and Breakpoint
  • How different gutter-positions affect your layout
  • How to build asymmetric layouts without breaking a sweat
  • How to use the isolation to prevent subpixel rounding errors

Partner with OddBird on Your Next Project!

We want to hear all about your software ideas. Fill out our contact form, join our public Slack chat, or tweet @oddbird to start the conversation.