Install from the command line:

# command line
gem install susy

Create a new Compass project:

# command line
compass create <project name> -r susy -u susy

Or update an existing Compass project:

# config.rb
require "susy"

Rails 3.x

# Gemfile
gem "susy"

You may also need:

# Gemfile
gem 'compass', '>= 0.12.2'
gem 'compass-rails', '>= 1.0.3'

And run:

# command line
bundle install


Edit your Gruntfile.js at the root level of your project and look for the Compass related rules, add the following inside the options object:

// Gruntfile.js
compass: {
    options: {
      require: 'susy',

Assuming you've already installed Susy, it will now be added to the project and will not clash with Yeomans grunt rules.

And you are good to go!

Manual Start

You can use this method if you're not using Compass from Terminal and/or Rails. This is going to work with CodeKit.


@import "susy";


Set up your default grid values: total columns, column width, and gutter width.

$total-columns  : 12;             // a 12-column grid
$column-width   : 4em;            // each column is 4em wide
$gutter-width   : 1em;            // 1em gutters between columns
$grid-padding   : $gutter-width;  // grid-padding equal to gutters

Basic Grids

The basic Susy grid is composed using two simple mixins:

Here's a simple page layout:

.page {
  // page acts as a container for our grid.
  @include container;

  // header and footer are full-width by default.
  header, footer { clear: both; }

  // nav spans 3 columns of total 12.
  nav { @include span-columns(3,12); }

  .content {
    // content spans the final (omega) 9 columns of 12.
    @include span-columns(9 omega,12);

    // main content spans 6 of those 9 columns.
    .main { @include span-columns(6,9); }

    // secondary content spans the final 3 (omega) of 9 columns.
    .secondary { @include span-columns(3 omega,9); }

Responsive Grids

Responsive Susy grids allow you to change the number of columns in a layout at different window sizes, using @media-queries with min and max widths. This requires one more mixin:

Here's a mobile-first example:

$total-columns: 4;

.page {
  // Establish our default 4-column grid container.
  @include container;

  // Create a media-query breakpoint at a min-width of 30em
  // And use a larger 8-column grid within that media-query.
  @include at-breakpoint(30em 8) {
    // Establish our new 8-column container.
    @include container;


Susy is built to handle your unique markup, and any number of edge cases. It includes the standard push() and pull() mixins, along with other useful functions and shortcuts, support for various grid styles, and even bi-directional grids for multi-lingual sites. Check the reference documentation for details.


Version Management

When you are working with bundled gems and dependencies across a number of different projects, managing gem versions can become an issue.

If you are working in a Ruby environment, we recommend using RVM. See our Rails troubleshooting below for some basic instructions, or dig into RVM's installation instructions.

In a Python environment, we recommend virtualenv in conjunction with these "postactivate" and "predeactivate" scripts to add support for Ruby gems.

Once you have that in place, Bundler can be used in either environment to manage the actual installation and updating of the gems.

Compass Install

The old gem and the new gem have different names, but are required simply as susy. That can cause a conflict if both gems are present.

If you have installed Susy in the past, make sure you've uninstalled older versions:

# command line
gem uninstall compass-susy-plugin
# "compass-susy-plugin" was the gem name for 0.9.x and lower
# Susy 1.0 switches to "susy" as the gem name

And then install 1.0:

# command line
gem install susy

Then use Compass as normal.

Rails 3.x Install

We recommend you use RVM for using Susy with Rails projects. It has become the standard gem management system for Rails, it's very easy to install and use, and it helps create and manage Gemsets among different developers working on different branches.

Here are some RVM best practices:

If you have installed Susy in the past, make sure you've uninstalled older versions. See Compass Install above.

Install RVM (These are basics, if you do not have Ruby and Rails already installed in your environment, we recommend you use RVM's installation instructions):

# command line
# from your system's root:
curl -L | bash -s stable

Create a gemset for your site:

# command line
rvm gemset create fooBar

Create an .rvmrc file at your site's root:

# .rvmrc
rvm use 1.9.3@fooBar
# Use whatever Ruby version number your app uses

Now whenever you cd into your site's root, RVM will pick up and use that Gemset.

cd to your site and install Bundler:

# command line
gem install bundler

Add Susy to your Gemfile (more info on Gemfiles):

gem "susy", "~> 1.0.9"

And finally run your bundle:

# command line