--- title: Reference class: guide side_content: >

Version 1.0.5

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: ; $total-columns: 12; - ``: Unitless number. #### Column Width The width of a single Column in your Grid. :::scss // $column-width: ; $column-width: 4em; - ``: Length in any unit of measurement (em, px, %, etc). #### Gutter Width The space between Columns. :::scss // $gutter-width: ; $gutter-width: 1em; - ``: Units must match `$column-width`. #### Grid Padding Padding on the left and right of a Grid Container. :::scss // $grid-padding: ; $grid-padding: $gutter-width; // 1em - ``: Units should match the container width (`$column-width` unless `$container-width` is set directly). ### Basic Mixins #### Container Establish the outer grid-containing element. :::scss // container([$]*) .page { @include container; } - `<$media-layout>`: Optional media-layout shortcuts (see '[Responsive Grids][responsive]' below). Default: `$total-columns`. [responsive]: #ref-responsive #### Span Columns Align an element to the Susy Grid. :::scss // span-columns(<$columns> [ , <$context>, <$padding>, <$from>]) nav { @include span-columns(3,12); } article { @include span-columns(9 omega,12); } - `<$columns>`: The number of _Columns_ to span. - ``: 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 | ]`. 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: ; // - You must supply either or . $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 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>`: Browsers interpret em-based media-queries using the browser default font size (`16px` in most cases). If you have a different base font size for your site, we have to adjust for the difference. Tell us your base font size, and we'll do the conversion. 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([, , , ]) { <@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](#ref-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 | ]`. 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 `` element as your _Container_, you need to apply a background to the `` 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](#ref-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: | ; $container-width: false; - ``: Length in em, px, %, etc. - ``: True or false. #### Container Style Override the type of shell containing your grid. :::scss // $container-style: