Susy 2.2.9¶

Layout [function]¶

Convert shorthand into a map of settings.

function

Format:	layout($layout)
$layout:	<layout>

// function input
$map: layout(auto 12 .25 inside fluid isolate);

//output
$map: (
  container: auto,
  columns: 12,
  gutters: .25,
  gutter-position: inside,
  math: fluid,
  output: isolate,
);

This is useful any time you need to combine settings stored in different variables. It’s not possible to combine two shorthand variables:

// THIS WON'T WORK
$short: 12 .25 inside;
@include layout($short fluid no-gutters);

but it is possible to add a map into the shorthand:

// THIS WILL WORK
$map: layout(12 .25 inside);
@include layout($map fluid no-gutters);

or combine two maps:

$map1: 13 static;
$map2: (6em 1em) inside;
@include layout($map1 $map2);

Layout [mixin]¶

Set a new layout as the global default.

mixin

Format:	layout($layout, $clean)
$layout:	<layout>
$clean:	<boolean>

// mixin: set a global layout
@include layout(12 1/4 inside-static);

By default, these new settings are added to your existing global settings. Use the $clean argument to establish new settings from scratch.

With Layout¶

Temporarily set defaults for a section of your code.

mixin

Format:	with-layout($layout, $clean) { @content }
$layout:	<layout>
$clean:	<boolean>
@content:	Sass content block

@include with-layout(8 static) {
  // Temporary 8-column static grid...
}

// Global settings are restored...

By default, these new settings are added to your existing global settings. Use the $clean argument to establish new settings from scratch.

Debug Image¶

Toggle the available grid images on and off.

setting

Key:	debug image
Scope:	global, local [container only]
Options:	show | hide | show-columns | show-baseline
Default:	hide

show

Show grid images, usually on the background of container elements, for the purpose of debugging. If you are using Compass vertical rhythms (or have set your own $base-line-height variable) Susy will show baseline grids as well.

hide

Hide all grid debugging images.

show-columns

Show only horizontal grid-columns, even if a baseline grid is available.

show-baseline

Show only the baseline grid, if the $base-line-height variable is available.

Debug Output¶

The debug image can be output either as a background on the container, or as a generated overlay.

setting

Key:	debug output
Scope:	global, local [container only]
Options:	background | overlay
Default:	background

background

Debugging images will be generated on on the background of the container element.

overlay

Debugging images will be generated as an overlay using the container’s ::before element. By default, the overlay is hidden, but we also generate a toggle in a corner of the viewport. Hover over the toggle to make the overlay appear.

Debug Toggle¶

If you are using the grid overlay option, Susy will generate a toggle to show/hide the overlay. Hovering over the toggle will show the overlay. You can place the toggle in any corner of the viewport using a combination of top, right, bottom, and left.

setting

Key:	debug toggle
Scope:	global
Options:	right | left and top | bottom
Default:	top right

Debug Color¶

Change the color of columns in the generated grid image.

setting

Key:	debug color
Scope:	global
Options:	<color>
Default:	rgba(#66f, .25)

Custom Clearfix¶

Tell Susy to use a global clearfix mixin.

setting

Key:	use-custom clearfix
Scope:	global
Options:	<boolean>
Default:	false

false

Susy will use an internal micro-clearfix.

true

Susy will look for an existing clearfix mixin, and fallback to the internal micro-clearfix if none is found.

Custom Background Image¶

Tell Susy to use a global background-image mixin. This is only used for debugging.

setting

Key:	use-custom background-image
Scope:	global
Options:	<boolean>
Default:	true

false

Susy will output background-images directly to CSS.

true

Susy will look for an existing background-image mixin (like the ones provided by Compass and Bourbon), and fallback to plain CSS output if none is found.

Custom Background Options¶

Tell Susy to use global background-size, -origin, and -clip mixins. This is only used for debugging.

setting

Key:	use-custom background-options
Scope:	global
Options:	<boolean>
Default:	false

false

Susy will output background-options directly to CSS.

true

Susy will look for existing background-size, -origin, and -clip mixins (like the ones provided by Compass and Bourbon), and fallback to plain CSS output if none is found.

Custom Breakpoint Options¶

Tell Susy to use a custom breakpoint mixin, like the one provided by the Breakpoint plugin.

setting

Key:	use-custom breakpoint
Scope:	global
Options:	<boolean>
Default:	true

false

Susy will use an internal fallback for media-queries.

true

Susy will look for existing an breakpoint mixin like the one provided by the [Breakpoint](http://breakpoint-sass.com) plugin, and fallback to internal media-query support if none is found.

Custom Box Sizing¶

Tell Susy to use a global box-sizing mixin.

setting

Key:	use-custom box-sizing
Scope:	global
Options:	<boolean>
Default:	true

false

Susy will output box-sizing official syntax, as well as -moz and -webkit prefixed versions.

true

Susy will look for an existing box-sizing mixin (like the ones provided by Compass and Bourbon), and fallback to mozilla, webkit, and official syntax if none is found.

Custom Rem¶

Tell Susy to use the Compass rem support module.

setting

Key:	use-custom rem
Scope:	global
Options:	<boolean>
Default:	true

false

Susy will output length values directly to CSS.

true

Susy will look for an existing rem mixin, and check the $rhythm-unit and $rem-with-px-fallback settings provided by Compass, or fallback to plain CSS output if they aren’t found.

Arbitrary Widths¶

For the simplest use, pass any width directly to the mixin:

// arbitrary width
.item { @include span(25%); }

// float output (without gutters)
.item {
  float: left;
  width: 25%;
}

Grid Widths¶

If you are using a grid, you can also span columns on the grid:

// grid span
.item { @include span(3); }

// output (7-column grid with 1/2 gutters after)
.item {
  float: left;
  width: 40%;
  margin-right: 5%;
}

Row Edges¶

When you use a grid with gutters before or after, you sometimes need to mark the first or last elements in a row, so Susy can remove the extra gutters:

// grid span
@include span(last 3);

// output (same 7-column grid)
.item {
  float: right;
  width: 40%;
  margin-right: 0;
}

For legacy reasons, alpha and omega can be used in place of first and last.

Context¶

Context is required any time you are using fluid math, and nesting grid elements inside other elements:

// 10-column grid
.outer {
  @include span(5);
  .inner { @include span(2 of 5); }
}

The of flag is used to signal context. The context is always equal to the grid-span of the parent. In some cases, you can imply changes in context by nesting elements inside the span tag itself:

// 10-column grid
.outer {
  // out here, the context is 10
  @include span(5) {
    // in here, the context is 5
    .inner { @include span(2); }
  }
}

Nesting¶

Grids with inside, inside-static, or split gutters don’t need to worry about the edge cases, but they do have to worry about nesting.

If an element will have grid-aligned children, you should mark it as a nest:

// inside, inside-static, or split gutters
.outer {
  @include span(5 nest);
  .inner { @include span(2 of 5); }
}

Location¶

Asymmetrical grids and isolated output also need to know the desired location of the span. In both cases, use the at flag to set a location.

For isolation, you can use either an arbitrary width or a column index (starting with 1). For asymmetrical grid spans, the location setting must be a column index:

.width { @include span(isolate 500px at 25%); }
.index { @include span(isolate 3 at 2); }

narrow, wide, and wider¶

By default, a grid span only spans the gutters between columns. So a span of 2 includes 1 internal gutter (narrow). In some cases you want to span additional gutters on either side. So that same span of 2 could include the internal gutter, and one (wide) or both (wider) external gutters.

// grid span
.narrow { @include span(2); }
.wide { @include span(2 wide); }
.wider { @include span(2 wider); }

// width output (7 columns, .25 gutters)
// (each column is 10%, and each gutter adds 2.5%)
.narrow { width: 22.5%; }
.wide { width: 25%; }
.wider { width: 27.5%; }

If you are using inside gutters, the spans are wide by default but can be overridden manually.

Other Settings¶

Use the full keyword to span the entire context available, use break to start a new Rows & Edges by clearing previous floats, and nobreak to clear none. Use no-gutters to remove gutter output from an individual span, and use border-box or content-box to output changes in box-sizing on the fly.

You can set an arbitrary gutter override, by passing a map (e.g. (gutter-override: 1.5em)) as part of the shorthand syntax.

You can also change the output style, grid context, and other global settings on the fly:

// grid span
.item { @include span(isolate 4 at 2 of 8 (4em 1em) inside rtl break); }

// output
.item {
  clear: both;
  float: right;
  width: 50%;
  padding-left: .5em;
  padding-right: .5em;
  margin-left: 25%;
  margin-right: -100%;
}

Break¶

mixin

Format:	break()
Reset:	nobreak()
Keywords:	break | nobreak

To create a new row, you need to clear all previous floats. This can usually be done using keywords with the span mixin. When you need to apply a row-break on it’s own, we have a break mixin.

.new-line { @include break; }

If you ever need to override that, you can use nobreak to set clear: none;.

.no-new-line { @include nobreak; }

Both break and nobreak can also be used as keywords with the span mixin.

First¶

mixin

Format:	first($context)
Alternate:	alpha($context)
$context:	<layout>

When gutter-position is set to before we need to remove the gutter from the first element in every row. This can often be solved using a keyword in the span mixin. Sometimes you need to set an item as first outside the span mixin.

.first { @include first; }

We also support an alpha mixin with the same syntax and output.

Both first and alpha can also be used as keywords with the span mixin.

Last¶

mixin

Format:	last($context)
Alternate:	omega($context)
$context:	<layout>

When gutter-position is set to after we need to remove the gutter from the last element in every row, and optionally float in the opposite direction. This can often be solved using a keyword in the span mixin. Sometimes you need to set an item as last outside the span mixin.

.last { @include last; }

We also support an omega mixin with the same syntax and output.

Both last and omega can also be used as keywords with the span mixin.

Full¶

mixin

Format:	full($context)
$context:	<layout>

This is a shortcut for span(full), used to create elements that span their entire context.

.last { @include full; }

full can also be used as a keyword with the span mixin.

Pre¶

mixin

Format:	pre($span)
Alternate:	push($span)
$span:	<span>

Add margins before an element, depending on the flow direction.

.example1 { @include pre(25%); }
.example2 { @include push(2 of 7); }

Post¶

mixin

Format:	post($span)
$span:	<span>

Add margins after an element, depending on the flow direction.

.example1 { @include post(25%); }
.example2 { @include post(2 of 7); }

Pull¶

mixin

Format:	pull($span)
$span:	<span>

Add negative margins before an element, pulling it against the direction of flow.

.example1 { @include pull(25%); }
.example2 { @include pull(2 of 7); }

Squish¶

mixin

Format:	squish($pre [, $post])
$pre:	<span>
$post:	[optional] <span>

Shortcut for adding both pre and post margins to the same element.

// equal pre and post
.example1 { @include squish(25%); }

// distinct pre and post
.example2 { @include squish(1, 3); }

When they share identical context, you can pass pre and post spans in the same argument. This is often the case, and saves you from repeating yourself.

// shared context
.shared {
  @include squish(1 3 of 12 no-gutters);
}

// distinct context
.distinct {
  @include squish(1 at 2, 3 at 6);
}

Prefix¶

mixin

Format:	prefix($span)
$span:	<span>

Add padding before an element, depending on the flow direction.

.example1 { @include prefix(25%); }
.example2 { @include prefix(2 of 7); }

Suffix¶

mixin

Format:	suffix($span)
$span:	<span>

Add padding after an element, depending on the flow direction.

.example1 { @include suffix(25%); }
.example2 { @include suffix(2 of 7); }

Pad¶

mixin

Format:	pad($prefix [, $suffix])
$prefix:	<span>
$suffix:	<span>

Shortcut for adding both prefix and suffix padding to the same element.

// equal pre and post
.example1 { @include pad(25%); }

// distinct pre and post
.example2 { @include pad(1, 3); }

When they share identical context, you can pass pre and post spans in the same argument. This is often the case, and saves you from repeating yourself.

// shared context
.shared {
  @include pad(1 3 of 12 no-gutters);
}

// distinct context
.distinct {
  @include pad(1 at 2, 3 at 6);
}

Bleed-x¶

mixin

Format:	bleed-x($bleed)
$bleed:	LR <span>

A shortcut for applying only left and right (horizontal) bleed.

// input
.example { @include bleed-x(1em 2em); }

// output
.example {
  margin-left: -1em;
  padding-left: 1em;
  margin-right: -2em;
  padding-right: 2em;
}

Bleed-y¶

mixin

Format:	bleed-y($bleed)
$bleed:	TB <span>

A shortcut for applying only top and bottom (vertical) bleed.

// input
.example { @include bleed-y(1em 2em); }

// output
.example {
  margin-top: -1em;
  padding-top: 1em;
  margin-bottom: -2em;
  padding-bottom: 2em;
}

Susy Breakpoint¶

mixin

Format:	susy-breakpoint($query, $layout, $no-query)
$query:	media query shorthand (see susy-media)
$layout:	<layout>
$no-query:	<boolean> | <string> (see susy-media)

susy-breakpoint() acts as a shortcut for changing layout settings at different media-query breakpoints, using either susy-media or the third-party Breakpoint plugin.

If you are using the third-party plugin, see Breakpoint: Basic Media Queries and Breakpoint: No Query Fallbacks for details.

This mixin acts as a wrapper, adding media-queries and changing the layout settings for any susy functions or mixins that are nested inside.

@include susy-breakpoint(30em, 8) {
  // nested code uses an 8-column grid,
  // starting at a 30em min-width breakpoint...
  .example { @include span(3); }
}

Susy Media¶

mixin

Format:	susy-media($query, $no-query)
$query:	<min-width> [<max-width>] | <string> | <pair> | <map>
$no-query:	<boolean> | <string>

The susy-media mixin provides basic media-query handling, and handles the built-in functionality for susy-breakpoint.

$query

A single length will be used as a min-width query, two lengths will become min- and max- width queries, a property-value pair, or map of pairs will become (property: value) queries, and a lonely string will be used directly.

// min
// ---
@include susy-media(30em) { /*...*/ }

@media (min-width: 30em) { /*...*/ }

// min/max pair
// ------------
@include susy-media(30em 60em) { /*...*/ }

@media (min-width: 30em) and (max-width: 60em) { /*...*/ }

// property/value pair
// -------------------
@include susy-media(min-height 30em) { /*...*/ }

@media (min-height: 30em) { /*...*/ }

// map
// ---
@include susy-media((
  min-height: 30em,
  orientation: landscape,
)) { /*...*/ }

@media (min-height: 30em) and (orientation: landscape) { /*...*/ }

$no-query

true will render the contents to css without any media-query. This can be useful for creating separate no-query fallback files.

For inline fallbacks using a target class, pass in a string (e.g. .no-mqs) to use as your fallback selector. The contents will be output both inside a media-query and again inside the given selector.

This can be set globally with the $susy-media-fallback variable.

susy-media also supports named media-queries, which can be set using the $susy-media variable:

$susy-media: (
  min: 20em,
  max: 80em 60em,
  string: 'screen and (orientation: landscape)',
  pair: min-height 40em,
  map: (
    media: screen,
    max-width: 30em
  ),
);

@include susy-media(min);

Total Columns¶

The number of Columns in your default Grid Layout.

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

• <number>: Unitless number.

Column Width¶

The width of a single Column in your Grid.

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

• <length>: Length in any unit of measurement (em, px, %, etc).

Gutter Width¶

The space between Columns.

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

• <length>: Units must match $column-width.

Grid Padding¶

Padding on the left and right of a Grid Container.

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

• <length>: Units should match the container width ($column-width unless $container-width is set directly).

Columns¶

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

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

• <$columns>: The number of Columns to span,
• <$context>: The Context. Default: $total-columns.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Gutter¶

The % width of one gutter in any given context.

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

• <$context>: The Context. Default: $total-columns.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Space¶

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

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

• <$columns>: The number of Columns to span,
• <$context>: The Context. Default: $total-columns.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Container¶

Establish the outer grid-containing element.

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

// span-columns(<$columns> [<omega> , <$context>, <$padding>, <$from>, <$style>])
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.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

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.
}

• <$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.

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

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; }
}

• <$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.

// 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 using container again.

// set-container-width([<$columns>, <$style>])
@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.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

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; }
};

• <$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.

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.

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

• <$location>: The container-relative column number to position on.
• <$context>: Current nesting Context. Default: $total-columns.
• <$from>: The origin direction of your document flow. Default: $from-direction.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Isolate Grid¶

Isolate a group of elements in a 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);
}

• <$columns>: The number of Columns for each item to span.
• <$context>: Current nesting Context. Default: $total-columns.
• <$selector>: either ‘child’ or ‘of-type’. Default: child.
• <$from>: The origin direction of your document flow. Default: $from-direction.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Prefix¶

Add Columns of empty space as padding before an element.

// prefix(<$columns> [, <$context>, <$from>, <$style>])
.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.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Suffix¶

Add columns of empty space as padding after an element.

// suffix(<$columns> [, <$context>, <$from>, <$style>])
.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.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Pad¶

Shortcut for adding both Prefix and Suffix padding.

// pad([<$prefix>, <$suffix>, <$context>, <$from>, <$style>])
.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.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

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);

• <$width>: The number of Columns or arbitrary length to bleed. Use 2 of 12 syntax for context in nested situations.
• <$sides>: The sides of the element that should bleed. Default: left right.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Pre¶

Add columns of empty space as margin before an element.

// pre(<$columns> [, <$context>, <$from>, <$style>])
.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.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Post¶

Add columns of empty space as margin after an element.

// post(<$columns> [, <$context>, <$from>, <$style>])
.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.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Squish¶

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

// squish([<$pre>, <$post>, <$context>, <$from>, <$style>])
.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.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

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); }

• <$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.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

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

• <$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.

// remove-omega([<$context>, <$from>, <$style>])
.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.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

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.
}

• <$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.
• <$style>: Optionally return static lengths for grid calculations. Default: $container-style.

Susy Grid Background¶

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

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

Container Width¶

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

// $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.

// $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%).

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;

• <direction>: left | right

Omega Float¶

The direction that Omega elements should be floated.

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

• <direction>: left | right

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;

• <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.

// $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-media-output¶

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

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

• <boolean>: true | false

$breakpoint-ie-output¶

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

// $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.

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

• <boolean>: true | false

Removed Settings¶

All the media-query fallback settings have been dropped. Susy 2 no longer manages media-queries, but we play well with other media-query libraries, and include special Breakpoint integration. See their documentation for handling legacy browsers.

We’ve also dropped $grid-padding as a setting. If you want to add padding to your container, you can easily do it by hand.

Translation¶

The remaining settings can be easily mapped into the new syntax.

$susy: (
  // the basics
  columns: $total-columns,
  gutters: $gutter-width / $column-width,
  column-width: $column-width,

  // advanced
  container: $container-width,
  math: if($container-style == magic, fluid, $container-style),
  flow: if($from-direction == right, rtl, ltr),
  last-flow: if($omega-float == $from-direction, from, to),
);

There are a few differences to note in the translation.

• You can set either column-width or container (or neither), but never both. One can be calculated from the other, but if you set both we don’t know which one should have priority.
• If you are using static math we highly recommend that you use column-width rather than container.
• The old magic style can be achieved through a combination of fluid math and a width setting (either column-width or container).

See 设置 for more details.

Columns / Space¶

The columns and space functions from SusyOne have now been merged into the new span function.

// columns/space: <span> [, <context>, <math>]
$columns: columns(3, 6, static);
$space: space(2, 7, fluid);

// span
$span-columns: span(3 of 6 static);
$span-space: span(2 of 7 fluid wide);

The difference between columns and space in the old syntax is now covered by the narrow and wide spread keywords (with narrow being the default in most cases).

Gutter¶

The gutter function remains, but the syntax has changed.

// gutter([<context>, <math>])
$old: gutter(6, static);
$new: gutter(6 static);

Container¶

The container mixin remains, but media-query support has been removed. For now, at least, you’ll have to establish one container at a time inside media-query declarations.

In most (fluid/magic) cases, we set up the container for our largest layout, and let it flex fluidly from there. If you need to change explicit sizes at explicit breakpoints, we recommend using the container function to override only the width at different breakpoints.

// old
body {
  @include container(4, 50em 8, 80em 12);
}

// new (simple)
body { @include container(12); }

// new (with breakpoint plugin)
body {
  @include container(4);
  @include breakpoint(50em) { max-width: container(8); }
  @include breakpoint(80em) { max-width: container(12); }
}

Span Columns¶

The span-columns mixin has been renamed span, and has much more power and flexibility. The old $padding argument has been removed, but everything else tranlates cleanly. Note that $from took right or left as options, where the new flow setting takes rtl or ltr.

// span-columns(<$columns> [<omega> , <$context>, <$padding>, <$from>, <$style>])
.old { @include span-columns(3 omega, 12, $padding, left, static); }
.new { @include span(last 3 of 12 ltr static); }

Omega¶

The omega mixin still esists, and should work without any changes. For readability, omega can be replaced with last, but that’s up to you.

nth-omega has been deprecated, in favor of omega with nth-child selectors.

.old { @include nth-omega(last); }
.new:last-child { @include omega; }

At-Breakpoint¶

Media-query support has been removed from the Susy core, because there are so many more powerful and flexible query-handling plugins. We recommend using Breakpoint, and we’ve written a translation of at-breakpoint (now called susy-breakpoint) that integrates smoothly with their controls.

.old {
  @include at-breakpoint(30em 8 60em) {
    // your 8-column media-query content...
  }
}

.new {
  @include susy-breakpoint(30em 60em, 8) {
    // your 8-column media-query content...
  }
}

This looks like a minor change, but it exposes a lot more power in both the media-queries and the changes to layout. See the Breakpoint docs for more detail on the former, and use our shorthand to control the latter in detail.

Layout & With-Grid-Settings¶

the layout and with-grid-settings mixins have merged to become with-layout. They continue to work much like before, with extra power exposed through the shorthand syntax.

// old
@include layout(12) { /* your 12-column layout */ }
@include with-grid-settings(8, 4em, 1em) { /* your custom layout */ }

// new
@include with-layout(12) { /* your 12-column layout... */ }
@include with-layout(8 (4em 1em)) { /* your custom layout */ }

There is still a mixin named layout, but it changes the global layout settings rather than wrapping a layout block.

// global layout
@include layout(12);

/* your 12-column layout... */

Set Container Width¶

The set-container-width mixin can be replaced by applying the container function to the width or max-width of your containing element.

// old
.fluid { @include set-container-width(8, fluid); }
.static { @include set-container-width(12, static); }

// new
.fluid { max-width: container(8); }
.static { width: container(12); }

Border-Box Sizing¶

The setting has changed from the boolean $border-box-sizing to the new global-box-sizing, but the border-box-sizing mixin works exactly like before.

Isolate¶

Isolation no longer requires it’s own mixin, as it can be controlled now through the span mixin for most cases. In those cases where you do still need a distinct mixin, isolate remains much like before.

.old { @include isolate(2, 12, left, static); }
.new { @include isolate(2 of 12 ltr static); }

Isolate Grid¶

the isolate-grid mixin has been renamed gallery, but is very similar in use.

.gallery-old { @include isolate-grid(3, 12, child, left, fluid); }
.gallery-new { @include gallery(3 of 12 left fluid, child); }

Only the selector argument remains split off from the others.

Margins and Padding¶

All the margin and padding mixins — pre, post, push, pull, prefix, suffix, pad, squish — remain unchanged, except that we now use the shorthand syntax in place of all the arguments.

See the new margins / padding documentation for details.

Bleed¶

Besides upgrading to the new shorthand, the bleed mixin now also supports TRBL syntax for applying to different sides, along with bleed-x and bleed-y shortcuts for horizontal and vertical bleed.

.old { @include bleed(2, left right); }
.new { @include bleed-x(2); }

Susy Grid Background¶

This has been renamed show-grid, and otherwise remains intact.

Reset-Columns / Remove-Omega¶

Susy One included reset-columns and remove-omega, but both have been deprecated. Rather than removing styles, override them with the desired behavior. The full and span mixins should give you everything you need for overriding spans and omegas, respectively.