Spanning The Grid

Singularity is what we like to call a semantic grid system, meaning that instead of grid classes being generated that you then apply to your HTML, the grid is stored entirely within your CSS and applied directly to the element you want to use it on. This makes working with responsive grids very easy as you don't need to swap classes using JavaScript or combine lots of assumptions into a single class. It also allows you to build and use grids that are not tied to specific sizes, allowing you to make more compelling and future friendly designs. The key to all of this is the grid-span mixin.

Grid Span

The key to spanning your grid is to use the grid-span mixin. The two inputs that are needed are $span and $location referring to how many columns you want to span, and what column you would like to start your calculation at. This combination of number of columns you are spanning and where you are starting your calculation from is your grid span. For symmetric grids, $location will not necessarily determine the total width of your grid span, but it is very important for asymmetric grids as the width of your grid span will change depending where on the grid you are. That being said, it is also important to know how your chosen output style will use both $span and $location. Let's take a look at a few examples:

$grids: 1 2 3 4 5;
$gutters: 1/3;
$output: 'float';

// Span 1 column, starting at the 2nd column
.span-1-2 {
  @include grid-span(1, 2);
}

// Span 3 columns, starting at the 5th column
.span-3-5 {
  @include grid-span(3, 5);
}

Context Overrides

The Grid Span mixin also takes optional inputs to allow you to override the global contexts for grids, gutters, and output styles on an as-needed basis. The first optional parameter, $grid, overrides the global grid context, $gutter the global gutter context, and $output-style the global output style context. Some examples of overriding are presented below:

$grids: 1 2 3 4 5;
$gutters: 1/3;
$output: 'float';

// Overrides the global Grid context provided by $grids with a 12 column symmetric grid
.override-grid-symmetric {
  @include grid-span(1, 2, 12);
}

// Overrides the global Grid context provided by $grids with a 2 4 5 asymmetric grid
.override-grid-asymmetric {
  @include grid-span(1, 2, (2 4 5));
}

// Overrides the global Gutter context provided by $gutters with a .25 gutter
.override-gutter {
  @include grid-span(1, 2, $gutter: .25);
}

// Overrides the global Output Style context provided by $output the Isolation output style
.override-output-style {
  @include grid-span(1, 2, $output-style: 'isolation');
}

// Overrides the global Grid context provided by $grids with a 12 column symmetric grid, the global Gutter context by $gutters with a .25 gutter, and the global Output Style context provided by $output with the Isolation output style
.override-all-the-things {
  @include grid-span(1, 2, 12, .25, 'isolation');
}

Grid Span Options

Finally, some Output Styles may have additional options that need to be taken into consideration. See the Output Styles documentation to see if an output has additional options it supports that should be passed in. If one does, simply pass the needed options in to the Grid Span mixin using the $options variable.