How to Use Susy with Bootstrap

Zell Liew
Zell Liew

Susy is a grid layout engine that was built to help web developers create web layouts easily. It allows us to create custom grids and it does its job extremely well.

One of the common complaints about Susy is that it is too simple, it’s only the grid layout engine. There are no UI kits that come with it, and that slows down developers who want to prototype quickly.

The good news is Susy can be integrated into almost any framework or UI kit, including the major ones, like Bootstrap and Foundation.

This is precisely what this tutorial is all about – integrating Susy with another framework, Bootstrap, to be specific. Even if you are not a fan of Bootstrap, you can still glean insights on how to integrate Susy with your UI kit of choice through this tutorial.

Assumptions and Results of This Tutorial

This tutorial assumes that you have some familiarity with Susy and Bootstrap.

If you are completely new to Bootstrap, I suggest you check out this tutorial by Fazle before continuing.

If you are completely new to Susy, I suggest that you check out my introductory tutorial on Susy first.

We are using Bower to install Bootstrap’s Sass package into the project because that would allow us to customise which files to include. You should also have Bower installed on your system before moving on.

For this tutorial, we are going to create part of Bootstrap’s homepage using Susy. We will also learn how to

  • Use buttons, forms, and other Bootstrap UI Elements
  • Customize Bootstrap variables for your project
  • Include only the necessary Bootstrap components to reduce the CSS and JS footprint.

This is an excerpt of the result that we will be making in the article.


Getting Started

First, create a new folder for your project and in terminal run the following command within it:

bower init

Bower will run an initialization process which looks like this:


Bower will create a summary, followed by a bower.json file after you entered your answers to the prompts.


Once the bower.json file is created, you can begin to install packages with the following command:

bower install <package-name>

Let’s begin by installing bootstrap-sass.

bower install bootstrap-sass

While we’re at it, let’s install two other components as well – normalize-scss and breakpoint-sass.

Normalize-scss is the Sass version of normalize.css, a web reset file by Nicolas Gallagher. We need normalize.css to make sure that our website is consistent across browsers.

Breakpoint-sass is a utility library by @import that helps make media queries much easier to handle.

bower install normalize-scss
bower install breakpoint-sass

Once installed, Bower packages can be found under apps/bower_components/component-name.

If you viewed the folders on your finder or windows explorer now, you’ll see five folders in the bower_components directory:


The two extra components, jQuery and sassy-maps, are installed by Bower automatically because Bootstrap requires jQuery to work while Breakpoint requires on sassy-maps to work.

The neat thing about Bower is that it installs these dependency packages for us.

Let’s create the project folders now that we have the packages ready. It should look like this:


And add styles.scss within the sass folder.

The first thing we need to do on any new website is to add normalize.scss into the project to normalise styles between browsers. If you have followed the above configuration, normalize.scss would be found within the bower_components folder.

The location to the file we need is ../app/bower_components/normalize-scss/normalize.

// Resets
@import "../app/bower_components/normalize-scss/normalize";

While we’re at this, let’s also include other packages like Susy and Bootstrap for the project.

@import "susy"; // Susy
@import "../app/bower_components/breakpoint-sass/stylesheets/breakpoint"; // Breakpoint
@import "../app/bower_components/bootstrap-sass/lib/bootstrap"; // Boostrap

Finally, make sure you link to both the styles.css, jQuery and Bootstrap’s js files in index.html

<!DOCTYPE html>
  <link rel="stylesheet" href="css/styles.css">
  <script src="app/bower_components/jquery/dist/jquery.min.js"></script>
  <script src="app/bower_components/bootstrap-sass/dist/js/bootstrap.js"></script>

That’s all for setting the project up. We now need a way to watch and compile Sass into CSS, and here is how you can do it with the terminal:

sass --watch scss:css -r susy

This command that tells the terminal to watch the scss folder for changes and output files into the css folder. Susy is installed as a gem and we need to run it with the -r susy flag.

You should get the following prompt when you run the above command.


Note: You can choose to compile Sass into CSS by other means such as Compass, Grunt, Codekit or Prepos, if you wish.

We can now begin integrating Susy with Bootstrap.

Using Susy with Bootstrap (The Theory)

In my last article with Sitepoint, I compared Susy with Bootstrap and pointed out that the only way to compare them was to compare their grids.

That’s a huge hint for the topic today. It doesn’t matter which framework we are talking about. Susy works well as long as you can switch the grids up.

Let’s make it clearer with an example. Say we’re trying to make a simple 3-column layout like this:


The HTML with Bootstrap is:

<div class="container">
  <div class="row">
    <div class="col-md-4"></div>
    <div class="col-md-4"></div>
    <div class="col-md-4"></div>

With Susy, we can discard the concept of having a .row, and set custom classes to each column. I also recommended switching up the .container class so we don’t get confused between bootstrap grids and our own Susy layout.

<div class="wrap">
  <div class="apple"></div>
  <div class="banana"></div>
  <div class="carrot"></div>

Susy works well with any class you decide to use. Although it would be fun to use fruits, a more practical choice are classes like .content and .sidebar.

These classes are semantic in nature and are great for a small website. But they can get difficult to scale and reuse as the website gets larger.

A better way of renaming these classes is to abstract out the grid classes into a parent class that serves as a layout pattern.

<div class="wrap">
  <div class="three-columns">
    <div class="grid-item"></div>
    <div class="grid-item"></div>
    <div class="grid-item"></div>

You can find more information about the why and how of writing classes in this way here.

Susy works wonderfully no matter how you name your classes. For now, let’s stick with the .three-columns pattern for the rest of this article.

We’ll need to write the Susy code for the classes that we have just created.

$susy: (
  columns: 12,
  container: 1140px,
  global-box-sizing: border-box,
  debug: (image: show)

  @include border-box-sizing;

  .wrap {
    @include container();

  .three-columns {
    @include clearfix;
    .grid-item {
      @include gallery(4);

That’s a quick primer on how to get started with a Susy grid. If this is confusing to you, I suggest that you take a step back and read this tutorial first

It’s easy to write media queries to augment Susy for a responsive design. While doing so, we want to make sure we write mobile-first media queries as much as possible.

Mobile-first media queries use the min-width query as much as possible, only changing layouts at a larger breakpoint.

In this case, the three columns can be shown as one in a smaller viewport and it will break into 3 columns at 760px. The styling for this would be:

.three-columns {
  @include clearfix
  .grid-item {
    @media (min-width: 760px) {
      @include gallery(4);

Since we have breakpoint-sass installed, we can opt to use the breakpoint mixin to handle media queries instead:

.three-columns {
  @include clearfix
  .grid-item {
    @include breakpoint(760px) {
      @include gallery(4);

We now have a grid with three items that are full width on mobile and breaks into 3 columns at 760px.


We now have flexibility over the grids, and the best part about all of this is that we can still use Bootstrap UI classes to create elements quickly!

<div class="wrap">
  <div class="three-columns">
    <div class="grid-item">
      <!-- Some buttons here -->
      <button href="#" class="btn btn-default btn-lg">This is a button!</button>
    <div class="grid-item">
      <!-- some form inputs here -->
      <input class="input-lg" type="text" placeholder="This is an input!">
    <div class="grid-item">
      <div class="alert alert-success">This is an alert!</div>


Here’s a Codepen to summarise what we have built so far. Try playing around with it and see how you can add inputs, buttons and other Bootstrap UI elements to it.

That’s how you would integrate Susy with Bootstrap on a beginner level.

One of the commonly cited problems with Bootstrap is code bloat, that there is a large amount of code you don’t actually use in your project. This might also be true for your framework of choice as well.

Let’s make the code 10x better by tearing Bootstrap apart and integrating only the components we need for the project.

Tearing Bootstrap Up

Bootstrap can be split into different CSS and JavaScript components. For CSS, we have to do to is to create a custom Bootstrap include file to include the necessary components. For JavaScript, we’ll just have to add individual JS components to the end of the html file.

Remove bootstrap.js from your html file to begin the process. We will add the JS components in the next section.

Then, create a separate file called _custom-bootstrap.scss within your project directory and import this file instead of Bootstrap’s default Sass file.

@import "susy"; // Susy
@import "../app/bower_components/breakpoint-sass/stylesheets/breakpoint"; // Breakpoint
@import "custom-bootstrap"; // Our own version of customized bootstrap

If you open up the original bootstrap.scss within the lib folder in bootstrap-sass, you’ll find a whole chunk of import codes:

// Core variables and mixins
@import "variables";
@import "mixins";

// Reset
@import "normalize";
@import "print";

// Core CSS
@import "scaffolding";
@import "type";
@import "code";
@import "grid";
@import "tables";
@import "forms";
@import "buttons";

// Components
@import "component-animations";
@import "glyphicons";
@import "dropdowns";
@import "button-groups";
@import "input-groups";
@import "navs";
@import "navbar";
@import "breadcrumbs";
@import "pagination";
@import "pager";
@import "labels";
@import "badges";
@import "jumbotron";
@import "thumbnails";
@import "alerts";
@import "progress-bars";
@import "media";
@import "list-group";
@import "panels";
@import "wells";
@import "close";

// Components w/ JavaScript
@import "modals";
@import "tooltip";
@import "popovers";
@import "carousel";

// Utility classes
@import "utilities";
@import "responsive-utilities";

These are the components and that make Bootstrap robust and popular, but much hated at the same time.

We do not need everything in most scenarios. Here are the files that we definitely need to have. Place these imports within the _custom-bootstrap.scss file.

// Core variables and mixins
@import "../app/bower_components/bootstrap-sass/lib/variables";
@import "../app/bower_components/bootstrap-sass/lib/mixins";

// Core CSS
@import "../app/bower_components/bootstrap-sass/lib/scaffolding";
@import "../app/bower_components/bootstrap-sass/lib/type";
@import "../app/bower_components/bootstrap-sass/lib/forms";
@import "../app/bower_components/bootstrap-sass/lib/buttons";

// Components
@import "../app/bower_components/bootstrap-sass/lib/component-animations";

It can helpful to replace the default bootstrap variables with your own variables when customising Bootstrap on a deeper level like what we are doing now.

This way, you can change variable inputs and quickly change the styles that Bootstrap outputs.

Create a _bootstrap-variables.scss in your project, import it, and copy the contents of Bootstrap’s variable file into this file.

// Core variables and mixins
@import "bootstrap-variables"; // Custom Bootstrap Variables
@import "../app/bower_components/bootstrap-sass/lib/mixins";

// Core CSS
@import "../app/bower_components/bootstrap-sass/lib/scaffolding";
@import "../app/bower_components/bootstrap-sass/lib/type";
@import "../app/bower_components/bootstrap-sass/lib/forms";
@import "../app/bower_components/bootstrap-sass/lib/buttons";

// Components
@import "../app/bower_components/bootstrap-sass/lib/component-animations";

We’re done setting up, let’s move on to build something real. We’re going to build a small part of the Bootstrap homepage, starting with the navigation.


The Navigation

Bootstrap’s navigation is straightforward if you are already familiar with Bootstrap.

The main idea is this:

  1. Create one separate div to hold the navigation toggle button which will show up on mobile viewports.
  2. Create another div to hold all the navigation links

We do not need Susy for the navigation in this layout. Everything can be done with Bootstrap.

<header class="navbar navbar-default" role="navigation">
  <div class="container-fluid">

    <!-- Menu Button for Toggling mobile nav -->
    <div class="navbar-header">
      <!-- data-target and data-target work together here to find the element to show or collapse. In this case, data-toggle looks for the class 'collapse' while data-target looks for the class 'bs-navbar-collapse' -->
      <button class="navbar-toggle" type="button" data-toggle="collapse" data-target=".bs-navbar-collapse">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      <a href="#" class="navbar-brand">Bootstrap</a>

    <!-- Menu (for both mobile and desktop) -->
    <nav class="collapse navbar-collapse bs-navbar-collapse" role="navigation">
      <ul class="nav navbar-nav">
        <li> <a href="#">Getting started</a> </li>
        <li> <a href="#">CSS</a> </li>
        <li> <a href="#">Components</a> </li>
        <li> <a href="#">JavaScript</a> </li>
        <li> <a href="#">Customize</a> </li>
      <ul class="nav navbar-nav navbar-right">
        <li><a href="#">Expo</a> </li>
        <li><a href="#">Blog</a> </li>

You can find out what Bootstrap components we need to include by looking at the HTML itself. It’s clear that we need the navs and navbar Sass components.

@import "../app/bower_components/bootstrap-sass/lib/navs";
@import "../app/bower_components/bootstrap-sass/lib/navbar";

The tricky thing here is to identify the Javascript files that are needed. If you looked at the HTML above, you’ll know that we need the collapse.js file for sure.

But what’s missing from the mix is that you’ll need the transitions.js file as well, and that’s not immediately apparent.

<!-- ... -->
<script src="app/bower_components/jquery/dist/jquery.min.js"></script>
<script src="app/bower_components/bootstrap-sass/js/transition.js"></script>
<script src="app/bower_components/bootstrap-sass/js/collapse.js"></script>


One more thing to note. This is often left unmentioned in most Bootstrap tutorials I find online.

When customizing the grid, it can be immensely helpful to change the breakpoint where the navigation goes into ‘mobile mode’ to match the customized grid layouts that we are going to code with Susy.

You can do so just by changing the $grid-float-breakpoint variable.

The navigation should work properly now. Let’s move on to the Masthead.



The HTML is relatively straightforward as well. You can almost pull the complete code from Bootstrap’s homepage and make some slight tweaks.

<div class="masthead">
  <div class="wrap">
    <!-- centred-content is a custom Susy layout -->
    <div class="centred-content">
      <span class="bootstrap-icon">B</span>
      <p class="lead">Bootstrap is the most popular HTML, CSS, and JS framework for developing responsive, mobile first projects on the web.</p>
        <!-- Note how you can still use Bootstrap buttons  -->
        <a href="#" class="btn btn-primary btn-lg">Download Bootstrap</a>
      <p class="version">Currently v3.2.0</p>

The difference here is that we now have a .centred-content div that is meant to take up 10 columns, with all text navigation centred within it.

The code for this .centred-content is:

.centred-content {
  text-align: center;
  @include breakpoint (760px) {
    @include span(10);
    margin-left: span(1 wide);

The margin-left of span(1 wide) pushes the content one column and one gutter inwards, resulting in a centralised content. If you have problems understanding how this work, I suggest you check this post out.

Notice how the button is given a btn-primary class in the HTML.

You can use btn-primary and btn-default classes in your Bootstrap layout as well once you have changed the styles for the buttons within the variables.

You can also change the .navbar styles as well, in case you were wondering :)

The Content

I’m going to end up repeating myself if we carry on like this. We’ve already discussed how and where we can use Susy with Bootstrap.

If you’re up for the challenge everything you need to move forward to complete the layout can be found in the examples above. Use those to work through the rest of the page and find where you can use Susy on Bootstraps markup.

As a bonus, here are the source files for the final product of this tutorial. Feel free to download this as a reference.

Hint: There are no additional JS files required for the remaining areas.


It turned out that this article was more about Bootstrap than Susy.

As you can see, it’s really simple to integrate Susy on a surface level, and keep everything from Bootstrap intact. It’s slightly tougher if you want to break up Bootstrap and only include files that are needed for your project.

The process for integrating Susy with your other frameworks is the same as well. It boils down to understanding both Susy and your framework and finding a way to meld them together.

Let me know in the comments if you have learnt something useful, want to ask a question or chat.