Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?
A new Susy tutorial

Susy 0.9 Tutorial

See the official Susy site for 1.0 documentation.

For this tutorial I'm assuming you are already comfortable with CSS, Sass (I'll use the SCSS syntax) and Compass. Please get set up with each one of those before attempting to use Susy. Sass and Compass both have their own setup instructions and tutorials that you can use.

There is also reference documentation in the works.

Building a Susy Grid

Step 1: Declare Your Grid

In the provided '_base' sass partial you have this:

$total-cols             : 12;  
$col-width              : 4em;  
$gutter-width           : 1em;  
$side-gutter-width      : $gutter-width;  

$total-cols is the number of columns in your grid, $col-width is the width of any one column, $gutter-width is the space between columns, and $side-gutter-width is the space between your outer columns and the edge of the container. Set each one to match your desired grid. The default above is elastic, but what if we want something else?

// Fixed Grid

$total-cols             : 6;  
$col-width              : 150px;  
$gutter-width           : 20px;  
$side-gutter-width      : 5px;

// Fluid Grid

$total-cols             : 24;  
$col-width              : 3%;  
$gutter-width           : 1%;  
$side-gutter-width      : 0%;

Step 2: Apply Your Grid

There are four main mixins required in the use of Susy: 'container', 'columns', 'alpha' and 'omega'. I'm only using non-semantic markup in these examples so that you can see what I am doing. Use the markup that you like. I'm also assuming the default elastic 12-column grid.

// Two-Sidebar Example SCSS

#container {  
  @include container;  
}

.left-sidebar {  
  @include columns(3);  
  @include alpha;  
}

.main-content {  
  @include columns(6);  
}

.right-sidebar {  
  @include columns(3);  
  @include omega;  
}

Compiled into CSS, we get the following (along with some clearfix and IE hasLayout help):

#container {  
  margin: auto;               /* centering */  
  width: 61em;                /* grid container size */  
  max-width: 100%;            /* responsive layout */  
}

.left-sidebar {  
  float: left;                /* float left */  
  width: 22.951%;             /* span 3 columns */  
  margin-right: 1.639%;       /* right gutter */  
  margin-left: 1.639%;        /* left side gutter */  
}

.main-content {  
  float: left;                  
  width: 47.541%;             /* span 6 columns */  
  margin-right: 1.639%;       
}

.right-sidebar {  
  float: right;               /* float right */  
  width: 22.951%;             /* span 3 columns */  
  margin-right: 1.639%;       /* right side gutter */  
}

Making Complex Grids

Nesting Columns

There are many ways to get more complex with Susy, but nesting columns inside other columns is probably the most common. And it's easy if you understand how Susy handles context. Once you start nesting columns, you need to know the width of the parent column in order to determine the relative width of the child. I've written a more detailed context demo that I recommend. This can be the trickiest part to understand. But here's how we might use it:

.main-content {  
  @include columns(6);      /* this will be our context for items nested inside it */
  
  .main-left-half {  
    @include columns(3,6);    /* 3 columns out of 6 */  
                              /* we don't need alpha when we are nested */  
  }
  
  .main-right-half {  
    @include columns(3,6);  
    @include omega(6);        /* we do need omega, this time with context */  
  }
}

That's all it takes. Here's the result for our two nested classes:

.main-content .main-left-half {  
  float: left;                  
  width: 48.276%;           /* 3 columns out of 6 */  
  margin-right: 3.448%;     /* right gutter */  
}

.main-content .main-right-half {  
  float: right;                  
  width: 48.276%;           /* 3 columns out of 6 */  
  margin-right: 0;          /* no right gutter */  
}

Prefix, Suffix and Shortcuts

Susy also provides some shortcuts for adding blank columns before and after the column you are working on. They work exactly like 'columns', but they add to the left and right padding of the element you are working on:

.column-with-padding {  
  @include columns(3,6);  
  @include prefix(1,6);  
  @include suffix(2,6);  
  @include omega(6);  
}

That will give us a width of 3 columns, with 1 column padding on the left and 2 columns padding on the right, all floated left, with no right gutter. We just used all six columns. Let's clean that up with some shortcuts.

The 'pad' shortcut allows us to add both prefix and suffix. The 'full' shortcut replaces columns, alpha and omega when we plan to span the full context:

.column-with-padding {  
  @include full(6);  
  @include pad(1,2,6);  
}

The only change in output is that Susy wont bother setting a width and floating it left. Why should we? The width will happen automatically, and the float isn't needed.

Accessing The Math with Functions

You can also access the math more directly and use it wherever you want with Susy's functions. The functions work exactly like their mixin counterparts, but only return the numbers:

.functions {  
  width: columns(3);  
  margin-right: gutter();  
  margin-left: columns(4) + gutter() + side-gutter();  
  padding-right: columns(1);  
}

Visualizing Your Grid

Susy includes a mixin to show you the grid as a background-image on your container element:

.container {  
    @include container;  
    @include susy-grid-background;  
}

Right-to-Left or Multi-Direction Grids

Susy now handles grids going in any direction, even multiple directions in one site. The simplest option is to change the $from-direction setting in your 'base' sass file. By default it is set to 'left'. Change that, and everything in Susy should just work:

$from-direction: right;

Now alpha columns will be on the right, and omega columns on the left. Gutters will be on the left of columns, etc. Everything works the same.

If you need to override the direction for specific widgets, all the affected mixins can be sent a final $from argument. Those mixins include columns, alpha, omega, prefix, suffix and pad:

.rtl-widget {  
  @include columns(3,6,right)  
  @include prefix(1,6,right)  
  @include omega(6,right)  
}

so the biggest problem i had with the tutorial is that there is no place to go look up the paramaters for your mixings i shouldn't have to read the entire tutorial to figure out what the 2nd and 3rd argument to column is

Owner

mirisuzanne commented Aug 22, 2011

Which really calls for page of documentation, not revision to the tutorial, right? I can work on that.

sure

Owner

mirisuzanne commented Aug 23, 2011

Reference Documentation (alpha): https://gist.github.com/1163918

@ericam Thanks a bunch for both the old and new tutorials. I am a newbie to Susy and after going through both, I think there is a lot of value in the old one as well -- though it is much longer, the html and pure css at the top add a lot of value and helps us try it out and see for ourselves what is going on without much struggle. May be have a link to the old one from the new one rather than discarding the old one?

Owner

mirisuzanne commented Aug 30, 2011

Glad you liked the suggestion, Eric.

This is old, right? I keep finding old tutorials on the internet that tell me to use @include full(); to make a full-width column, but that doesn't seem to be part of the API anymore. Right?

Yep full() was removed. This tutorial is mostly correct though.

http://susy.oddbird.net/guides/upgrade-1-0/

"full has been removed entirely. Elements will be full-width by default. You can add clear: both; back in as needed."

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment