A Complete Tutorial to Susy

Susy is a plugin to Compass that allows you to create customizable grid frameworks easily. It makes responsive design extremely easy by removing the need to manually calculate widths.

If you need to create repsonsive websites do not want to constrain your design with available frameworks out in the open, Susy might be the perfect answer.

This is the first of a two part tutorial that covers the basics of Susy.

In this tutorial, we are going to install Susy, set up Susy defaults and understand how to create the 10-column complex nested grid AG test found on the susy website.

Important Update

Susy 2 is now released, which makes this tutorial obsolete. Head over here to find the latest article on Susy 2 instead.

Installing Susy

Susy requires Sass and Compass.

This tutorial assumes that you already have Sass and Compass installed. If not, I suggest you check out some awesome video tutorials at LevelUpTuts for Sass and Compass.

Once you have Sass and Compass installed, go ahead and install Susy from the command line:

# Command line
$ sudo gem install susy

Important Note: Susy has been upgraded to Susy 2, and a lot of the configurations is changed. If you have any errors running Susy, I would recommended you to uninstall all versions of Sass, Compass and Susy, and reinstall them altogether. The most important thing here is that sass and compass needs to upgrade if you are using old versions (I have no clue how to update so I just reinstalled everything)

sudo gem uninstall sass
sudo gem uninstall compass 
sudo gem uninstall susy 

# I personally use --pre, but you should be able to get by without the --pre since Susy 2.0 was officially released. 
sudo gem install sass --pre
sudo gem install compass --pre 
sudo gem install susy --pre 

The process to use Susy in a project is to add a line of code in the config.rb found in the compass.

# in config.rb 
require 'susy'

Now, we can get into the very basics of using Susy.

Setting up Susy

The very first step of using Susy in your project is to import Susy in your sass file and set its defaults.

@import "_normalize.scss"; 
// To revert all browser default styles 

@import "susyone"; 
// susy is now reserved for susy 2. For the rest of this tutorial, you have to use susyone instead of importing "susy" as in previous versions.


// Configuring Susy defaults
// Susy accepts px, em and rem for the magic and fixed grid, and % for the fluid grid
$total-columns: 10;
$column-width: 4rem;
$gutter-width: 1rem;    
$grid-padding: $gutter-width / 2; 

$container-style: magic; // default to magic. Switch to fluid or fixed if desired

I’ll also recommend using border boxes to help you with creating layouts. Susy has a built-in mixin for border-box sizing. Read on about border-box over at CSS Tricks if have no idea what it is.

@include border-box-sizing;

Also, the susy grid background helps alot when trying to understand how columns are placed.

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

With this, we are now ready to tackle the 10 column AG test.

Setting Up The AG Grid Test

This is what we are going to obtain by the end of the tutorial

Susy Example AG 1 - AG 10

The HTML

The HTML for the grid test is as follows.

<div class="container">
<h1>The 10 column complex nested grid AG test</h1>

<div class="ag ag1">
  <h2>AG 1</h2>
</div>
<!-- /ag1 -->

<!-- ag3 to ag7 are nested within ag2.-->
<div class="ag ag2">
  <h2>AG 2</h2>
  <div class="ag ag4">
    <h2>AG 4</h2>
  </div>
  <div class="ag ag5">
    <h2>AG 5</h2>
  </div>
  <div class="ag ag6">
    <h2>AG 6</h2>
  </div>

  <!-- ag8, ag9 and ag10 are nested within ag7 -->
  <div class="ag ag7">
    <h2>AG 7</h2>
    <div class="ag ag8">
      <h2>AG 8</h2>
    </div>
    <div class="ag ag9">
      <h2>AG 9</h2>
    </div>
    <div class="ag ag10">
      <h2>AG 10</h2>
    </div>
  </div>
  <!-- /ag7 -->
</div>
<!-- /ag2 -->

<div class="ag ag3">
  <h2>AG 3</h2>
</div>
<!-- /ag3 -->

</div>
<!-- /container -->

Simply speaking, whenever something is found within another div, you should nest it within the previous div.

In our case, AG 3 to AG 7 will be nested under AG 2 while AG 8, AG 9 and AG 10 are nested under AG 7.

The Sass

We’re going give each ag a color like the one on Susy’s main webpage.

/**
 * Styles for AG grids & Container
 */

.container {
  background-color: #fbeecb;
}

.ag1, .ag3 {
  background-color: #71dad2;
}

.ag2 {
  background-color: #fae7b3;
}

.ag4,.ag5,.ag8,.ag9 {
  background-color: #ee9e9c;
}

.ag6 {
  background-color: #f09671;
}

.ag7 {
  background-color: #f6d784;
}

.ag10 {
  background-color: #ea9fc3;
}

/**
 * Text Styles
 */
h2 {
  text-align: center;
  font-size: 1rem;
  font-weight: normal;
  padding-top: 1.8rem;
  padding-bottom: 1.8rem;
}

Susy Mixins and Functions

Before diving into writing susy mixins, I hope you wont mind if I explained how they work.

Container

Container establishes the grid containing element for the webpage. Given our html, the container mixin will be applied to the container class. This tells Susy where to start all the calculations from.

.container {
 @include container;
}

If were are to use Susy with responsive design, we have to pass some arguments into container. This will be elaborated on in part 2 of the tutorial.

Span Columns

The Span Column mixin is probably the one used most while using Susy. It allows you to align an element to the grid you would like defined.

The span column mixin takes a minimum of 1 argument and has the potential to accept a few more to customize to your needs.

 @include span-columns( <$columns> [ <omega> , <$context>, <$padding>, <$from>, <$style>])

The most important arguments to be included here in span-columns are $columns, omega and $context. The rest of the explanation can be viewed on the Susy Reference page.

  • $columns means the number of columns you would like the particular element to take up.

  • omega is an optional flag to tell Susy that this is the final element in a row.

  • $context tells Susy the current nesting context. It defaults to the total number of columns you specified within the container. In our case, it is 10.

Since we’re clear of the two basic mixins used, we can start applying them to create the grid.

Using Susy for the AG Grid Test

As we have mentioned above, we need to tell Susy what is the containing element for the Susy grid. In our case, the containing element is .container.

We must also make the container clear its childrens since Susy makes use of floats to align our grids. For simplicity, I’m using overflow hidden as the self clearing method here. Other methods can be found on Chris Coyier’s page.

.container {
  @include container;
  overflow: hidden;
}

Lets start applying susy span column mixins to the rest of our grids. Taking the image as a reference, we count that ag1 takes up 2 columns, ag2 takes up 6 columns and ag3 takes up the final two columns.

.ag1 {
  @include span-columns(2);
}

.ag2 {
  @include span-columns(6, 10);
  // Optionally, you can choose to include the context.
}
.ag3 {
  @include span-columns(2 omega);
  // The omega flag is set here to tell Susy that ag3 is the final column. 
}

This CSS output Susy has created for us.

.container {
  *zoom: 1;
  // Susy has calculated and provided fallbacks in px for the rem unit I used 
  max-width: 784px;
  max-width: 49rem;
  _width: 784px;
  padding-left: 0;
  padding-right: 0;
  margin-left: auto;
  margin-right: auto;
  overflow: hidden; }

.ag1 {
  width: 18.36735%; // Size of 2 columns + 1 Gutter
  float: left;
  margin-right: 2.04082%;
  display: inline; }

.ag2 {
  width: 59.18367%; // Size of 6 columns + 5 Gutters
  float: left;
  margin-right: 2.04082%;
  display: inline; }

.ag3 {
  width: 18.36735%; 
  float: right; // Omega flag creates a float right instead of float left
  margin-right: 0;
  *margin-left: -1rem;
  display: inline; }
Susy Example AG 1 to AG 3

Susy takes into account the container’s width at 49rem (or 784px) and proceeds to convert all our calculations into percentages. Its alot simpler to work with numbers like 2 and 6 instead of absolute percentages!

Although this doesn’t seem like much right now, you will see that its extremely awesome when responsive design comes into play in the next tutorial.

Let’s proceed to complete the rest of the grids that are within AG 2.

Creating Elements Within AG 2.

Here, we have to be very careful with the $context because $context defaults to the $total-columns, which was declared right at the top of our Sass file.

If left untouched, Susy will use 10 columns to calculate the width of everything within AG 2.

AG 2 consists of 6 columns and we want our items within the grid to have a context of 6 columns as well. In this case, we have to specify the context manually with the number 6.

The rest of the mixins can be used in the same manner as above.

.ag2 {
  // overflow hidden is used to self clear children
  overflow: hidden; 
}

.ag4 {
  // Specifying the context with 6
  @include span-columns(3, 6);
}

.ag5 {
  // Additionally, adding omega to signify the last column
  @include span-columns(3 omega, 6);
}

.ag6 {
  @include span-columns(2, 6);
}

.ag7 {
  @include span-columns(4 omega, 6);
}

Susy Example AG 1 - AG 7 What’s left now is everything within the AG 7 column.

Creating Elements Within AG 7

Repeat the process with everything you have done with the elements in AG 2. The context within AG 7 is 4 columns.

.ag7 {
  overflow: hidden;
}

.ag8 {
  @include span-columns(2, 4);
}

.ag9 {
  @include span-columns(2 omega, 4);
}

.ag10 {
  // There is no need to use span columns on AG 10 since elements take up 100% of the space by default in display block. In this case, we just have to make sure to clear the floats from ag8 and ag9. 
  clear: both;

  // You can still use span-columns if you want to though. There's no fault in using that. 
  @include span-columns(4, 4);
}

And we’re done!

Susy Example AG 1 - AG 10

Feel free to grab the source code and view the demo:

View Demo Download Source

Wrapping Up the First Part

I hope this quick tutorial has given you the opportunity to familiarize yourself with Susy and to understand how span columns and containers are used.

In the next part of the tutorial next week, we will cover the use of Susy with responsonsive designs, altering the AG grid at various sizes. We will also look into using some of Susy’s helper mixins that provides additional padding or magin to really make our design fully customized.

Want more of this?

Get similar articles as soon as they are published

  • Mohamad Elbialy

    Hey Zell,
    I was lost till I found this tutorial, now things are a bit easier for me and I’ve some confidence in using Susy, looking for more of the These great tutorials.

  • http://jitendravyas.com/ Jitendra Vyas

    I didn’t get this @include span-columns(6, 10);

    • http://www.zell-weekeat.com/ Zell Liew

      Are you familiar with Sass?

      If you are, you’ve probably heard of mixins. The @include span-column(6,10) is a mixin provided along with the Susy add-on that helps to calculate the width of the selector.

      • http://jitendravyas.com/ Jitendra Vyas

        Yes I use Sass and Compass. I actually didn’t get why we add “10″ here

        • http://www.zell-weekeat.com/ Zell Liew

          10 is for context.

          Basically in this mixin, we’re telling Susy that this HTML element will use 6 out of 10 columns.

          This is especially important for nested elements, like AG4 and AG5. You’ll have to tell Susy the total number of columns used in here is 8, and AG4 takes 4 columns.

          So @include span-columns(4,8);

          • Thomas

            Hi,
            Is there any chance to have a tutorial for Susy 2 ?

            Thanks

          • http://www.zell-weekeat.com/ Zell Liew

            It’s in the works

          • Thomas

            Great news!

          • http://www.zell-weekeat.com/ Zell Liew

            incase you wanted to know, I have the Susy 2 Tutorial up now

          • Thomas

            Thanks for letting me know. I will go through it today.

  • http://jitendravyas.com/ Jitendra Vyas

    on .ag10 @include span-columns(4, 4); is not necessary but if i don’t add it decreases it’s height.

    • http://www.zell-weekeat.com/ Zell Liew

      Yup I agree the final span-columns(4,4) is not necessary. If you have content within it then its fine. Just remember to give it a clearfix if you have floated contents within .ag10. Otherwise you can just leave it be.

  • http://jitendravyas.com/ Jitendra Vyas

    This tutorial is complete and I really enjoyed it. Now looking forward for 2nd part http://www.zell-weekeat.com/a-complete-tutorial-to-susy-part-2/

  • Behinder

    Nice tutorial, however I still cannot force divs with such classes to extend vertically. overflow:hidden NOT doing the trick :(

    • http://www.zell-weekeat.com/ Zell Liew

      I suppose if you are trying this tutorial, the problem might be because you didn’t have a height for each div.

      Overflow hidden clears floats here, they don’t give a height to each item.

      • Behinder

        I found the solution. I had something like and two styles was generated one for id and other for the class, so probably the ID style has precedense.

  • Minh Phạm

    Hey Zell,
    I hope you will have a tutorial about the new verson – Susy 2.

    • http://www.zell-weekeat.com/ Zell Liew

      Hey Minh, I’ll definitely try out Susy next when it comes out of alpha. Will likely blog about that as well.

      • Minh Phạm

        Thanks a lot! Can you share your workflow in your works? What tools do you use in web design?

        • http://www.zell-weekeat.com/ Zell Liew

          I generally start with sketches in pencil and paper, then move on to photoshop.

          Recently though, I’ve started experimenting with style tiles and trying out a different tool called Macaw.

          Then I move into code.

          Does that help?

  • cliftoo

    What does AG mean?

    • http://www.zell-weekeat.com/ Zell Liew

      AG is simply a class name given to that particular box.

  • Eugenia Jongewaard

    Thanks!!! the susy documentation is not very easy to read I was about to give up of using Susy until I saw this tutorial :D

    • http://www.zell-weekeat.com/ Zell Liew

      Glad that it helped :)

  • http://www.thomas-hirt.at Thomas Hirt

    Hello!

    I am trying to follow your tutorial but can’t get it to work.
    If I write the line: @import “_normalize.scss”;

    I get the following error:
    error sass/style.scss (Line 6: File to import not found or unreadable: _normalize.scss.

    I am on a mac and have the latest susy installed.
    Do you have a hint?

    Greetings from Vienna,
    Thomas

    • http://www.zell-weekeat.com/ Zell Liew

      Hey Thomas,

      I forgot to mention that you should include normalize.scss as a form of reset. This is added as another sass file, within the same folder.

      The link to download normalise is http://necolas.github.io/normalize.css/

      I hope I’m not confusing you. normalise has nothing to do with susy.

      • http://www.thomas-hirt.at Thomas Hirt

        Sorry, I am new to compass and susy.

        So I downoad normalize.css, rename it to normalize.scss and place it in hte folder sass… Right?

        Bye,
        Thomas

        • http://www.zell-weekeat.com/ Zell Liew

          Yes, download normalize.css and rename it as _normalize,scss

          The reason for the _ in front of normalize scss is because we’re saying that this is a “partial”. “Partials” will not be compiled into a separate stylesheet, but combined into the main styles.scss stylesheet.

          Is that much clearer for you now?

          • http://www.thomas-hirt.at Thomas Hirt

            Yes it is. Still having this problem:

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

            Terminal says:
            error sass/style.scss (Line 18: Undefined mixin ‘susy-grid-background’.)
            It is not easy to start with this ;)

            Great support. Thank you

          • http://www.zell-weekeat.com/ Zell Liew

            I hope you’re not using Susy 2 here. The grid background works differently.

            Did you install Susy with the suffix –pre?

            As in did you type

            sudo gem install susy –pre

            or

            sudo gem install susy?

          • http://www.thomas-hirt.at Thomas Hirt

            Yes, I did install Susy with the suffix –pre!

            Now I did:
            sudo gem uninstall susy

            Then:
            sudo gem install susy

            Still:
            sass/style.scss (Line 18: Undefined mixin ‘susy-grid-background’.)

            How can I find out wich susy I’ve got installed?
            Thanks,
            Thomas

          • http://www.thomas-hirt.at Thomas Hirt

            It makes me crazy. If I install https://rubygems.org/gems/susy/versions/1.0.9 it says:
            error sass/style.scss (Line 25 of _support.scss: Undefined variable: “$experimental-support-for-mozilla”.)

            This seems to be more difficult than I thought. Maybe because I am on a mac?

            Thanks,
            Thomas

          • http://www.zell-weekeat.com/ Zell Liew

            forget what I just said.

            It seems that version 2.0 is already rolled out with gem install susy. Its not an alpha version anymore.

            What you should do instead is to install everything on –pre

            So
            sudo gem install sass –pre
            sudo gem install compass –pre
            sudo gem install susy –pre

            That should work.

          • http://www.thomas-hirt.at Thomas Hirt

            Sorry but it does not work as expected:

            sudo gem install sass –pre
            Successfully installed sass-3.3.2

            sudo gem install compass –pre
            Successfully installed compass-1.0.0.alpha.18

            sudo gem install susy –pre
            Successfully installed susy-2.0.0

            It seems to install susy 2.
            I am sorry to bother you with this so much…

            Thomas

          • http://www.zell-weekeat.com/ Zell Liew

            Thomas its cool. Leave the susy two alone.

            Now go back to the part where I mentioned @import “susy”. Change that to @import “susyone”.

            Things should work again.

            I’ve updated the tutorial, so you can follow along from the beginning again. Let me know if you run into problems

          • http://www.thomas-hirt.at Thomas Hirt

            Great… This seems to work. Thank you very much.
            Do you know a place where I can start with compass and learn more of susy?
            If you have some useful links this would be cool.
            Have a sunny day,
            Thomas

          • http://www.zell-weekeat.com/ Zell Liew

            First of all I think you should get yourself familiarised with Sass and Compass before even trying to touch Susy.

            Levelup tuts is a good resource for these two.
            http://leveluptuts.com/tutorials/sass-tutorials
            http://leveluptuts.com/tutorials/compass-tutorials

            You probably don’t need to run through every single lesson though. Just the basic first (9)? lessons should suffice.

            For Susy, I reckon this page is the best place to start :)

          • http://www.thomas-hirt.at Thomas Hirt

            OK, thank you for the links. I’ll work it out.

            Ciao and thank you again!
            Thomas

            PS:
            I had to remove the following line from your demo code:

            .ag {
            @include border-radius(5px);
            }

            It will break the output.

          • http://www.zell-weekeat.com/ Zell Liew

            No problem.

            Just curious, how does it break the output? It didn’t break for me.

          • http://www.thomas-hirt.at Thomas Hirt

            It says:

            error sass/style.scss (Line 121: Undefined mixin ‘border-radius’.)

            The rest seems to work fine.
            Maybe again a problem with the versions?

            Thanks,
            Thomas

          • http://www.zell-weekeat.com/ Zell Liew

            Did you remember to include compass in the scss file?

            @import “compass”;

          • http://www.zell-weekeat.com/ Zell Liew

            Thats why!

            This tutorial is meant to be with susy one, and that I had problems with the experimental support as well. I believe its because of some dependency issues with Compass & Sass or something.

            What I did was to uninstall all 3 of them and reinstall them.

            so

            sudo gem uninstall susy
            sudo gem uninstall compass
            sudo gem uninstall sass

            Then

            sudo gem install sass
            sudo gem install compass
            sudo gem install susy.

            Then proceed on as what the tutorial mentioned above.

            That should work

        • http://www.zell-weekeat.com/ Zell Liew

          Yes, download normalize.css and rename it as normalise,scss

          For a start you can use the folder structure shown in the image

          The reason for the _ in front of normalize scss is because we’re saying that this is a “partial”. “Partials” will not be compiled into a separate stylesheet, but combined into the main styles.scss stylesheet.

          Is that much clearer for you now?

  • rick

    I am not sure if it accurate in saying that the reason why you need to use ‘susyone’ is because ‘susy’ is a reserved word in susy 2. ‘susyone’ from the documentation is a flag in order to use susy one syntax while having susy 2 installed. http://susydocs.oddbird.net/en/latest/susyone/ Other than that GREAT post!!

    • http://www.zell-weekeat.com/ Zell Liew

      I guess I just over explained myself :)