The Susy 2.0 toolkit is built around our shorthand syntax. Use the shorthand to control every detail, and adjust your defaults on-the-fly, so you are never tied down to just one grid, or just one output style.
Set any element to span a portion of your layout. For a floated or isolated layout, this will add necessary floats, widths, and margins.
| Format: | span($span) { @content } |
|---|---|
| $span: | <span> |
| @content: | Sass content block |
There are many ways to use the span mixin...
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%;
}
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%;
}
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 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); }
}
}
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); }
}
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); }
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.
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%;
}
The span function is identical to the span mixin, but returns only the span width value, so you can use it with custom output.
| Format: | span($span) |
|---|---|
| $span: | <span> |
.item {
width: span(2);
margin-left: span(3 wide);
margin-right: span(1) + 25%;
}
| Format: | gutters($span) |
|---|---|
| Alternate: | gutter($span) |
| $span: | <span> |
Use gutter or gutters as a function to return the width of a gutter given your settings and current context.
// default context
margin-left: gutter();
// nested in a 10-column context
margin-left: gutter(10);
Use the mixin version to apply gutters to any element. Gutters are output as margin or padding depending on the gutter-position setting.
// default gutters
.item { @include gutters; }
You can also set explicit gutter widths:
// explicit gutters
.item { @include gutters(3em); }
Or use the shorthand syntax to adjust settings on the fly:
// inside gutters
.item { @include gutters(3em inside); }
// gutters after, in an explicit (10 1/3) layout context
.item { @include gutters(10 1/3 after); }
| Format: | container($layout) |
|---|---|
| $layout: | <layout> |
Use the container function to return a container-width based on an optional layout argument, or your global settings.
// global settings
width: container();
// 12-column grid
$large-breakpoint: container(12);
Use the mixin to apply container settings to an element directly.
body {
@include container(12 center static);
}
Note that static math requires a valid column-width setting
| Function: | nested($span) |
|---|---|
| Mixin: | nested($span) { @content } |
| $span: | <span> |
| @content: | Sass content block |
Sass is not aware of the DOM, or the specific markup of your site, so Susy mixins don’t know about any ancestor/child relationships. If your container creates a grid context that is different from the default, you will need to pass that new context explicitly to nested elements.
You can pass that context along with the shorthand syntax.
body { @include container(8); }
.span { @include span(3 of 8); }
But that gets repetitive if you have large blocks of code using a given context. The nested mixin provides a shortcut to change the default context for a section of code.
@include nested(8) {
.span { @include span(3); }
}
Context is a bit more complex when you are using asymmetrical grids, because we need to know not just how many columns, but which columns are available.
.outer {
@include span(3 of (1 2 3 2 1) at 2);
// context is now (2 3 2)...
.inner { @include span(2 of (2 3 2) at 1); }
}
The nested function can help you manage context more easily, without having to calculate it yourself.
$grid: (1 2 3 2 1);
.outer {
$context: 3 of $grid at 2;
@include span($context);
@include nested($context) {
.inner { @include span(2 at 1); }
}
}
Set the box-sizing on a global selector, and set the global-box-sizing to match.
| Format: | global-box-sizing($box [, $inherit]) |
|---|---|
| Shortcut: | border-box-sizing([$inherit]) |
| $box: | content-box | border-box |
| $inherit: | [optional] true | false |
Setting the optional argument, $inherit, to true will still globally set the box-sizing, but in a way such that a component can easily override the global box-sizing by setting its own box-sizing property. By setting box-sizing once on the component, all nested elements within the component will also be modified. The default behavior, where $inherit is false, would only update the box-sizing of the component itself. Nested elements are not affected when $inherit is false.
You can pass a box-sizing argument to the span mixin as part of the shorthand syntax, and Susy will set the element’s box-sizing to match.
// input
.item { @include span(25em border-box); }
// sample output (depending on settings)
.item {
float: left;
width: 25em;
box-sizing: border-box;
}
We highly recommend using a global border-box setting, especially if you are using inside gutters of any kind.
// the basics with default behavior:
* { box-sizing: border-box; }
// the basics with $inherit set to true:
html { box-sizing: border-box; }
* { box-sizing: inherit; }
Susy needs to know what box model you are using, so the best approach is to set global box sizing using one of Susy’s shortcuts.
// the flexible version:
@include global-box-sizing(border-box);
// the shortcut:
@include border-box-sizing;
If you want to change the global box-sizing by hand, or it has already been changed by another library, update the global-box-sizing setting to let Susy know.
If you need to supprot IE6/7, there is a simple polyfill to make it work.
Floated layouts sometimes require help maintaining rows and edges.
| 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.
| Format: | first($context) |
|---|---|
| Alternate: | alpha($context) |
| $context: | <layout> |
Note
Only useful when gutter-position is set to before.
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.
| Format: | last($context) |
|---|---|
| Alternate: | omega($context) |
| $context: | <layout> |
Note
Only required when gutter-position is set to after, but can be useful in any context to help with sub-pixel rounding issues.
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.
| 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.
Shortcut mixins for applying left/right margins.
| 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(25%); }
.example3 { @include pre(2 of 7); }
.example4 { @include push(2 of 7); }
| 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); }
| 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); }
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);
}
Shortcut mixins for applying left/right padding.
Note
The interaction between padding and width changes depending on your given box-model. In the browser-default content-box model, width and padding are added together, so that an item with span(3) and prefix(2) will occupy a total of 5 columns. In the recommended border-box model, padding is subtracted from the width, so that an item with span(3) will always occupy 3 columns, no matter what padding is applied.
| 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); }
| 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); }
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);
}
| Format: | bleed($bleed) |
|---|---|
| $bleed: | TRBL <span> |
Apply negative margins and equal positive padding, so that element borders and backgrounds “bleed” outside of their containers, without the content be affected.
This uses the standard span shorthand, but takes anywhere from one to four widths, using the common TRBL pattern from CSS.
// input
.example1 { @include bleed(1em); }
.example2 { @include bleed(1em 2 20px 5% of 8 .25); }
// output
.example1 {
margin: -1em;
padding: 1em;
}
.example2 {
margin-top: -1em;
padding-top: 1em;
margin-right: -22.5%;
padding-right: 22.5%;
margin-bottom: -20px;
padding-bottom: 20px;
margin-left: -5%;
padding-left: 5%;
}
When possible, the bleed mixins will attempt to keep gutters intact. Use the no-gutters keyword to override that behavior.
| Format: | isolate($isolate) |
|---|---|
| $isolate: | <span> |
Isolation is a layout technique based on floats, but adjusted to address sub-pixel rounding issues. Susy supports it as a global output setting, or as a Shorthand keyword for the span mixin, or as a stand-alone mixin.
The $isolate argument takes a standard span shorthand, but any length or grid-index given is interpreted as an isolation location (unless location is otherwise specified with the at flag). The function returns a length value.
// input
.function {
margin-left: isolate(2 of 7 .5 after);
}
// output
.function {
margin-left: 15%;
}
And the mixin returns all the properties required for isolation.
// input
.mixin { @include isolate(25%); }
// output
.mixin {
float: left;
margin-left: 25%;
margin-right: -100%;
}
| Format: | gallery($span, $selector) |
|---|---|
| $span: | <span> |
| $selector: | (nth-) child* | of-type |
Gallery is a shortcut for creating gallery-style layouts, where a large number of elements are laid out on a consistent grid. We take the standard span shorthand and apply it to all the elements, using nth-child or nth-of-type selectors and the isolation technique to arrange them on the grid.
// each img will span 3 of 12 columns,
// with 4 images in each row:
.gallery img {
@include gallery(3 of 12);
}
Warning
The nth-child selector has issues on iOS8 Safari. Use nth-of-type for iOS8 support.
| Format: | show-grid($grid) |
|---|---|
| $grid: | <layout> |
The easiest way to show you grids is by adding a keyword to your container mixin. If you need to apply the grid separately, the show-grid mixin takes exactly the same layout shorthand arguments, and can output the debugging grid image as either a background, or a triggered overlay.
body {
@include container;
@include show-grid(overlay);
}
Warning
Grid images are not exact. Browsers have extra trouble with sub-pixel rounding on background images. These are meant for rough debugging, not for pixel-perfect measurements. Expect the to side of your grid image (right if your flow is ltr) to be off by several pixels.
Susy has built-in media-query handling, and also supports integration with the Breakpoint plugin. To install Breakpoint, follow the instuctions on their site.
| 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); }
}
| 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.
// 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) { /*...*/ }
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);