Basic Usage

@import 'susy';

Basic Settings

Total Columns

The number of Columns in your default Grid Layout.

// $total-columns: <number>;
$total-columns: 12;

Column Width

The width of a single Column in your Grid.

// $column-width: <length>;
$column-width: 4em;

Gutter Width

The space between Columns.

// $gutter-width: <length>;
$gutter-width: 1em;

Grid Padding

Padding on the left and right of a Grid Container.

// $grid-padding: <length>;
$grid-padding: $gutter-width;  // 1em

Basic Mixins

Container

Establish the outer grid-containing element.

// container([$<media-layout>]*)
.page { @include container; }

Span Columns

Align an element to the Susy Grid.

// span-columns(<$columns> [<omega> , <$context>, <$padding>, <$from>, <$style>])
nav { @include span-columns(3,12); }
article { @include span-columns(9 omega,12); }

Omega

Apply to any omega element as an override.

// omega([<$from>])
.gallery-image {
  @include span-columns(3,9); // each gallery-image is 3 of 9 cols.
  &:nth-child(3n) { @include omega; } // every third image completes a row.
}

Nth-Omega

Apply to any element as an nth-child omega shortcut. Defaults to :last-child.

// nth-omega([<$n>, <$selector>, <$from>])
.gallery-image {
  @include span-columns(3,9); // each gallery-image is 3 of 9 cols.
  @include nth-omega(3n); // same as omega example above.
}

Responsive Grids

Media-Layouts

// $media-layout: <min-width> <layout> <max-width> <ie-fallback>;
// - You must supply either <min-width> or <layout>.
$media-layout: 12;          // Use 12-col layout at matching min-width.
$media-layout: 30em;        // At min 30em, use closest fitting layout.
$media-layout: 30em 12;     // At min 30em, use 12-col layout.
$media-layout: 12 60em;     // Use 12 cols up to max 60em.
$media-layout: 30em 60em;   // Between min 30em & max 60em, use closest layout.
$media-layout: 30em 12 60em;// Use 12 cols between min 30em & max 60em.
$media-layout: 60em 12 30em;// Same. Larger length will always be max-width.
$media-layout : 12 lt-ie9;  // Output is included under `.lt-ie9` class,
                            // for use with IE conditional comments
                            // on the <html> tag.

Responsive Mixins

At-Breakpoint

At a given min- or max-width Breakpoint, use a given Layout.

// at-breakpoint(<$media-layout> [, <$font-size>]) { <@content> }
@include at-breakpoint(30em 12) {
  .page { @include container; }
}

Layout

Set an arbitrary Layout to use with any block of content.

// layout(<$layout-cols>) { <@content> }
@include layout(6) {
  .narrow-page { @include container; }
}

Set Container Width

Reset the width of a Container for a new Layout context. Can be used when container() has already been applied to an element, for DRYer output than simply using container again.

// set-container-width([<$columns>, <$style>])
@include container;
@include at-breakpoint(8) {
  @include set-container-width;
}

With Grid Settings

Use different grid settings for a block of code - whether the same grid at a different breakpoint, or a different grid altogether.

// with-grid-settings([$<columns>, $<width>, <$gutter>, <$padding>]) { <@content> }
@include with-grid-settings(12,4em,1.5em,1em) {
  .new-grid { @include container; }
};

Grid Helpers

Box Sizing

Border-Box Sizing

Set the default box-model to border-box, and adjust the grid math accordingly.

// border-box-sizing()
@include border-box-sizing;

This will apply border-box model to all elements (using the star selector) and set $border-box-sizing to true. You can use the variable on it's own to adjust the grid math, in cases where you want to apply the box-model separately.

Isolation

Isolate

Isolate the position of a grid element relative to the container. This should be used in addition to span-columns as a way of minimizing sub-pixel rounding errors in specific trouble locations.

// isolate(<$location> [, <$context>, <$from>, <$style>])
@include span-columns(4); // 4-columns wide
@include isolate(2); // positioned in the second column

Isolate Grid

Isolate a group of elements in an grid (such as an image gallery) using nth-child or nth-of-type for positioning. Provide the column-width of each element, and Susy will determine the positioning for you.

// isolate-grid(<$columns> [, <$context>, <$selector>, <$from>, <$style>])
.gallery-item {
  @include isolate-grid(3);
}

Padding Mixins

Prefix

Add Columns of empty space as padding before an element.

// prefix(<$columns> [, <$context>, <$from>, <$style>])
.box { @include prefix(3); }

Suffix

Add columns of empty space as padding after an element.

// suffix(<$columns> [, <$context>, <$from>, <$style>])
.box { @include suffix(2); }

Pad

Shortcut for adding both Prefix and Suffix padding.

// pad([<$prefix>, <$suffix>, <$context>, <$from>, <$style>])
.box { @include pad(3,2); }

Bleed

Add negative margins and matching positive padding to an element, so that its background "bleeds" outside its natural position.

// bleed(<$width> [<$sides>, <$style>])
@include bleed(2);

Margin Mixins

Pre

Add columns of empty space as margin before an element.

// pre(<$columns> [, <$context>, <$from>, <$style>])
.box { @include pre(2); }

Post

Add columns of empty space as margin after an element.

// post(<$columns> [, <$context>, <$from>, <$style>])
.box { @include post(3); }

Squish

Shortcut to add empty space as margin before and after an element.

// squish([<$pre>, <$post>, <$context>, <$from>, <$style>])
.box { @include squish(2,3); }

Push

Identical to pre.

// push(<$columns> [, <$context>, <$from>, <$style>])
.box { @include push(3); }

Pull

Add negative margins before an element, to pull it against the flow.

// pull(<$columns> [, <$context>, <$from>, <$style>])
.box { @include pull(2); }

Reset Mixins

Reset Columns

Resets an element to default block behaviour.

// reset-columns([<$from>])
article { @include span-columns(6); }     // articles are 6 cols wide
#news article { @include reset-columns; } // but news span the full width
                                          // of their container

Remove-Omega

Apply to any previously-omega element to reset it's float direction and margins to match non-omega grid elements. Note that unlike omega, this requires a context when nested.

// remove-omega([<$context>, <$from>, <$style>])
.gallery-image {
  &:nth-child(3n) { @include remove-omega; } // 3rd images no longer complete rows.
}

Remove Nth-Omega

Apply to any previously nth-omega element to reset it's float direction and margins to match non-omega grid elements. Note that unlike omega, this requires a context when nested.

// remove-nth-omega([<$n>, <$selector>, <$context>, <$from>, <$style>])
.gallery-image {
  @include remove-nth-omega(3n); // same as remove-omega example above.
}

Other Mixins

Susy Grid Background

Show the Susy Grid as a background-image on any container.

// susy-grid-background();
.page { @include susy-grid-background; }

Functions

Where a mixin returns property/value pairs, functions return simple values that you can put where you want, and use for advanced math.

Columns

Similar to span-columns mixin, but returns the math-ready % multiplier.

// columns(<$columns> [, <$context>, <$style>])
.item { width: columns(3,6); }

Gutter

The % width of one gutter in any given context.

// gutter([<$context>, <$style>])
.item { margin-right: gutter(6) + columns(3,6); }

Space

Total % space taken by Columns, including internal AND external gutters.

// space(<$columns> [, <$context>, <$style>])
.item { margin-right: space(3,6); }

Container Override Settings

Container Width

Override the total width of your grid with an arbitrary length.

// $container-width: <length> | <boolean>;
$container-width: false;

Container Style

Override the type of shell containing your grid.

// $container-style: <style>;
$container-style: magic;

Direction Override Settings

From Direction

The side of the Susy Grid from which the flow starts. For ltr documents, this is the left.

// $from-direction: <direction>;
$from-direction: left;

Omega Float

The direction that Omega elements should be floated.

// $omega-float: <direction>;
$omega-float: opposite-position($from-direction);

Compass Options

Base Font Size

From the Compass Vertical Rhythm module, Susy uses your base font size to help manage em-based media-queries.

// $base-font-size: <px-size>;
$base-font-size: 16px;

Browser Support

Susy recognizes all the Compass Browser Support variables, although only IE6 and IE7 have special cases attached to them currently.

// $legacy-support-for-ie  : <boolean>;
// $legacy-support-for-ie6 : <boolean>;
// $legacy-support-for-ie7 : <boolean>;
$legacy-support-for-ie  : true;
$legacy-support-for-ie6 : $legacy-support-for-ie;
$legacy-support-for-ie7 : $legacy-support-for-ie;

Breakpoint Output

If you are compiling seperate files for IE-fallbacks, it can be useful to output only the modern code in one file and only the fallbacks in another file. You can make at-breakpoint do exactly that by using the following settings.

$breakpoint-media-output

Turn off media-query output for IE-only stylesheets.

// $breakpoint-media-output: <boolean>;
$breakpoint-media-output: true;

$breakpoint-ie-output

Turn off media-query fallback output for non-IE stylesheets.

// $breakpoint-ie-output: <boolean>;
$breakpoint-ie-output: true;

$breakpoint-raw-output

Pass through raw output without media-queries or fallback classes for IE-only stylesheets.

// $breakpoint-raw-output: <boolean>;
$breakpoint-raw-output: false;