Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

653 lines (516 sloc) 23.593 kB
title class side_content
Reference
guide

Version 1.0.1

Basic Usage

Basic Settings

Basic Mixins

Responsive Grids

Responsive Mixins

Grid Helpers

Box Sizing

Padding Mixins

Margin Mixins

Reset Mixins

Other Mixins

Functions

Container Override Settings

Direction Override Settings

Compass Options

Breakpoint Output

Basic Usage

:::scss
@import 'susy';
  • Container: The root element of a Grid.
  • Layout: The total number of Columns in a grid.
  • Grid Padding: Padding on the sides of the Grid.
  • Context: The number of Columns spanned by the parent element.
  • Omega: Any Grid Element spanning the last Column in its Context.

Basic Settings

Total Columns

The number of Columns in your default Grid Layout.

:::scss
// $total-columns: <number>;
$total-columns: 12;
  • <number>: Unitless number.

Column Width

The width of a single Column in your Grid.

:::scss
// $column-width: <length>;
$column-width: 4em;
  • <length>: Length in any unit of measurement (em, px, %, etc).

Gutter Width

The space between Columns.

:::scss
// $gutter-width: <length>;
$gutter-width: 1em;
  • <length>: Units must match $column-width.

Grid Padding

Padding on the left and right of a Grid Container.

:::scss
// $grid-padding: <length>;
$grid-padding: $gutter-width;  // 1em
  • <length>: Units must match $column-width.

Basic Mixins

Container

Establish the outer grid-containing element.

:::scss
// container([$<media-layout>]*)
.page { @include container; }
  • <$media-layout>: Optional media-layout shortcuts (see 'Responsive Grids' below). Default: $total-columns.

Span Columns

Align an element to the Susy Grid.

:::scss
// span-columns(<$columns> [<omega> , <$context>, <$padding>, <$from>])
nav { @include span-columns(3,12); }
article { @include span-columns(9 omega,12); }
  • <$columns>: The number of Columns to span.
    • <omega>: Optional flag to signal the last element in a row.
  • <$context>: Current nesting Context. Default: $total-columns.
  • <$padding>: Optional padding applied inside an individual grid element. Given as a length (same units as the grid) or a list of lengths (from-direction to-direction). Default: false.
  • <$from>: The origin direction of your document flow. Default: $from-direction.

Omega

Apply to any omega element as an override.

:::scss
// 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.
}
  • <$from>: The origin direction of your document flow. Default: $from-direction.

Nth-Omega

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

:::scss
// 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.
}
  • <$n>: The keyword or equation to select: [first | only | last | <equation>]. An equation could be e.g. 3 or 3n or '3n+1'. Note that quotes are needed to keep complex equations from being simplified by Compass. Default: last.
  • <$selector>: The type of element, and direction to count from: [child | last-child | of-type | last-of-type ]. Default: child.
  • <$from>: The origin direction of your document flow. Default: $from-direction.

Responsive Grids

  • Breakpoint: A min- or max- viewport width at which to change Layouts.
  • Media-Layout: Shortcut for declaring Breakpoints and Layouts in Susy.

Media-Layouts

:::scss
// $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.
  • <$min/max-width>: Any length with units, used to set media breakpoints.
  • <$layout>: Any (unitless) number of columns to use for the grid at a given breakpoint.
  • <$ie-fallback>: Any string to use as a fallback class when mediaqueries are not available. Do not include a leading "." class-signifier, simply the class name ("lt-ie9", not ".lt-ie9"). This can be anything you want: "no-mediaqueries", "ie8", "popcorn", etc.

Responsive Mixins

At-Breakpoint

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

:::scss
// at-breakpoint(<$media-layout> [, <$font-size>]) { <@content> }
@include at-breakpoint(30em 12) {
  .page { @include container; }
}
  • <$media-layout>: The Breakpoint/Layout combo to use (see above).
  • <$font-size>: When using EMs for your grid, the font size is important. Default: $base-font-size.
  • <@content>: Nested @content block will use the given Layout.

Layout

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

:::scss
// layout(<$layout-cols>) { <@content> }
@include layout(6) {
  .narrow-page { @include container; }
}
  • <$layout-cols>: The number of Columns to use in the Layout.
  • <@content>: Nested @content block will use the given Layout.

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.

:::scss
// set-container-width([<$columns>])
@include container;
@include at-breakpoint(8) {
  @include set-container-width;
}
  • <$columns>: The number of Columns to be contained. Default: Current value of $total-columns depending on Layout.

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.

:::scss
// with-grid-settings([<columns>, <width>, <gutter>, <padding>]) { <@content> }
@include with-grid-settings(12,4em,1.5em,1em) {
  .new-grid { @include container; }
};
  • <$columns>: Overrides the $total-columns setting for all contained elements.
  • <$width>: Overrides the $column-width setting for all contained elements.
  • <$gutter>: Overrides the $gutter-width setting for all contained elements.
  • <$padding>: Overrides the $grid-padding setting for all contained elements.
  • <@content>: Nested @content block will use the given grid settings.

Grid Helpers

Box Sizing

Border-Box Sizing

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

:::scss
// 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.

Padding Mixins

Prefix

Add Columns of empty space as padding before an element.

:::scss
// prefix(<$columns> [, <$context>, <$from>])
.box { @include prefix(3); }
  • <$columns>: The number of Columns to be added as padding before.
  • <$context>: The Context. Default: $total-columns.
  • <$from>: The origin direction of your document flow. Default: $from-direction.

Suffix

Add columns of empty space as padding after an element.

:::scss
// suffix(<$columns> [, <$context>, <$from>])
.box { @include suffix(2); }
  • <$columns>: The number of Columns to be added as padding after.
  • <$context>: The Context. Default: $total-columns.
  • <$from>: The origin direction of your document flow. Default: $from-direction.

Pad

Shortcut for adding both Prefix and Suffix padding.

:::scss
// pad([<$prefix>, <$suffix>, <$context>, <$from>])
.box { @include pad(3,2); }
  • <$prefix>: The number of Columns to be added as padding before.
  • <$suffix>: The number of Columns to be added as padding after.
  • <$context>: The Context. Default: $total-columns.
  • <$from>: The origin direction of your document flow. Default: $from-direction.

Margin Mixins

Pre

Add columns of empty space as margin before an element.

:::scss
// pre(<$columns> [, <$context>, <$from>])
.box { @include pre(2); }
  • <$columns>: The number of Columns to be added as margin before.
  • <$context>: The Context. Default: $total-columns.
  • <$from>: The origin direction of your document flow. Default: $from-direction.

Post

Add columns of empty space as margin after an element.

:::scss
// post(<$columns> [, <$context>, <$from>])
.box { @include post(3); }
  • <$columns>: The number of Columns to be added as margin after.
  • <$context>: The Context. Default: $total-columns.
  • <$from>: The origin direction of your document flow. Default: $from-direction.

Squish

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

:::scss
// squish([<$pre>, <$post>, <$context>, <$from>])
.box { @include squish(2,3); }
  • <$pre>: The number of Columns to be added as margin before.
  • <$post>: The number of Columns to be added as margin after.
  • <$context>: The Context. Default: $total-columns.
  • <$from>: The origin direction of your document flow. Default: $from-direction.

Push

Identical to pre.

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

Pull

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

:::scss
// pull(<$columns> [, <$context>, <$from>])
.box { @include pull(2); }
  • <$columns>: The number of Columns to be subtracted as margin before.
  • <$context>: The Context. Default: $total-columns.
  • <$from>: The origin direction of your document flow. Default: $from-direction.

Reset Mixins

Reset Columns

Resets an element to default block behaviour.

:::scss
// 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
  • <$from>: The origin direction of your document flow. Default: $from-direction.

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.

:::scss
// remove-omega([<$context>, <$from>])
.gallery-image {
  &:nth-child(3n) { @include remove-omega; } // 3rd images no longer complete rows.
}
  • <$context>: Current nesting Context. Default: $total-columns.
  • <$from>: The origin direction of your document flow. Default: $from-direction.

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.

:::scss
// remove-nth-omega([<$n>, <$selector>, <$context>, <$from>])
.gallery-image {
  @include remove-nth-omega(3n); // same as remove-omega example above.
}
  • <$n>: The keyword or equation to select: [first | only | last | <equation>]. An equation could be e.g. 3 or 3n or '3n+1'. Note that quotes are needed to keep a complex equation from being simplified by Compass. Default: last.
  • <$selector>: The type of element, and direction to count from: [child | last-child | of-type | last-of-type ]. Default: child.
  • <$context>: Current nesting Context. Default: $total-columns.
  • <$from>: The origin direction of your document flow. Default: $from-direction.

Other Mixins

Susy Grid Background

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

:::scss
// susy-grid-background();
.page { @include susy-grid-background; }
  • If you are using the <body> element as your Container, you need to apply a background to the <html> element in order for this grid-background to size properly.
  • Some browsers have trouble with sub-pixel rounding on background images. Use this for checking general spacing, not pixel-exact alignment. Susy columns tend to be more accurate than gradient grid-backgrounds.

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.

:::scss
// columns(<$columns> [, <$context>])
.item { width: columns(3,6); }
  • <$columns>: The number of Columns to span,
  • <$context>: The Context. Default: $total-columns.

Gutter

The % width of one gutter in any given context.

:::scss
// gutter([<$context>])
.item { margin-right: gutter(6) + columns(3,6); }
  • <$context>: The Context. Default: $total-columns.

Space

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

:::scss
// space(<$columns> [, <$context>])
.item { margin-right: space(3,6); }
  • <$columns>: The number of Columns to span,
  • <$context>: The Context. Default: $total-columns.

Container Override Settings

Container Width

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

:::scss
// $container-width: <length> | <boolean>;
$container-width: false;
  • <length>: Length in em, px, %, etc.
  • <boolean>: True or false.

Container Style

Override the type of shell containing your grid.

:::scss
// $container-style: <style>;
$container-style: magic;
  • <style>: magic | static | fluid.
    • magic: Susy's magic grid has a set width, but becomes fluid rather than overflowing the viewport at small sizes.
    • static: Susy's static grid will retain the width defined in your settings at all times.
    • fluid: Susy's fluid grid will always be based on the viewport width. The percentage will be determined by your grid settings, or by $container-width, if either is set using % units. Otherwise it will default to auto (100%).

Direction Override Settings

From Direction

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

:::scss
// $from-direction: <direction>;
$from-direction: left;
  • <direction>: left | right

Omega Float

The direction that Omega elements should be floated.

:::scss
// $omega-float: <direction>;
$omega-float: opposite-position($from-direction);
  • <direction>: left | right

Compass Options

Base Font Size

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

:::scss
// $base-font-size: <px-size>;
$base-font-size: 16px;
  • <px-size>: Any length in px. This will not actually effect your font size unless you use other Vertical Rhythm tools, we just need to know. See Compass Docs for further usage details.

Browser Support

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

:::scss
// $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;
  • <boolean>: true | false

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.

:::scss
// $breakpoint-media-output: <boolean>;
$breakpoint-media-output: true;
  • <boolean>: true | false

$breakpoint-ie-output

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

:::scss
// $breakpoint-ie-output: <boolean>;
$breakpoint-ie-output: true;
  • <boolean>: true | false

$breakpoint-raw-output

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

:::scss
// $breakpoint-raw-output: <boolean>;
$breakpoint-raw-output: false;
  • <boolean>: true | false
Jump to Line
Something went wrong with that request. Please try again.