Gridle{.scss}

Tired of searching for a simple, really customizable and powerful grid system? Look no further.

Get started

Below is the basic usage of gridle and how to use it in your own project.

I have a question about this...

Get Started

Below is the basic usage of gridle and how to use it in your own project. From here you can make adjustments to the setup and states to suit your specific needs.

Installation

To install gridle in your project, you can use one of these options

$ npm install gridle
$ bower install gridle
$ gem install gridle

Or simply by downloading the package : Download the package

Files structure

This is the file structure that we use in our project. Feel free to adapt this depending on your needs...

_settings.scss

This file contains all your grid setup instructions.

// import gridle
@import "gridle/gridle";

// setting up the grid
@include gridle_setup( (
    context : 12,
    gutter-width : 20px,
    direction : rtl,
    // etc...
) );

// make the use of media queries really easy
@include gridle_register_state ( mobile , (
    max-width : 480px 
) );
@include gridle_register_state ( tablet , (
    min-width : 481px,
    max-width : 1024px
) ) ;

// even with full custom queries :
@include gridle_register_state ( landscape, (
    query : "(orientation : landscape)"
) );

grid.scss

This file will be your actual grid classes. You need to import the settings and use the gridle_generate_classes mixin in order to get your classes.

// import settings :
@import 'settings';

// generate classes :
@include gridle_generate_classes ( );

// manage container width :
.container {
    max-width : 960px;
    margin : 0 auto;
}

index.html

Here's how you use your grid classes in your html.

<!-- If want to use mixins, no need to add classes -->
<div class="container">
    <div class="gr-12" id="header">
        I'm the header, 12 columns width
    </div>
    <div class="gr-8 gr-12@mobile" id="content">
        I'm the content, 8 columns width, but 12 on mobile
    </div>
    <div class="gr-4 gr-12@mobile" id="sidebar">
        I'm the sidebar, 4 columns width, but 12 on mobile
    </div>
</div>

style.css

In your style.scss file, you need also to include the settings, then you can use all the gridle mixins inside your code like so:

// import settings :
@import 'settings';

#header {
    @include gridle_grid ( 12 );
}
#content {
    @include gridle_grid ( 8 );
    @include gridle_state ( mobile ) {
        @include gridle_grid ( 12 );
    }
}
#sidebar {
    // sidebar will make 4 columns width
    @include gridle_grid ( 4 );
    background : yellow ;

    // update sidebar look and feel for mobile and tablet
    @include gridle_state (  mobile tablet  ) {
        background : red;
    }
}

Setup

Gridle is a fully customizable grid system. To do that, you have to configure your grid with simple options.

Configure your grid

In order for Gridle to work, the gridle_setup() mixin needs to be run. This is where you can pass core configuration variables like the amount of columns (context) and the width of the gutter.

@include gridle_setup( {settings} );
// default settings
$settings : (
    context : 12,           // number of columns in your grid
    gutter-width : 20px,    // size of the gutters
    gutter-height : 0,      // size of top and bottom gutters
    gutter-top    : 0,      // size of top gutter
    gutter-bottom : 0,      // size of bottom gutter
    gutter-left   : 10px,   // size of left gutter
    gutter-right  : 10px,   // size of right gutter
    direction : ltr,        // direction
    states-classes : false, // if we need to generate the states classes
    name-multiplicator : 1, // if 5, generate gr-5, gr-10, etc...
    classes-prefix : ''     // the prefix used for all classes 
);
@include gridle_setup($settings);

You need to specify only the settings that you want to override

Make sure that your states do not have the same name as a gridle option like gutter-width...

Init your grid

If you use the grid with the gridle_generate_classes mixin only, this is not for you. When you use gridle with the mixins, you have to init it in order to avoid some potential issues with libsass (sorry it's not me who's in charge of this project...). To do that, it's really simple. You have to call the gridle_init() mixin AFTER the section where you have all your gridle setup kind of mixins (this includes gridle_setup, gridle_register_states, etc...) and BEFORE you call any gridle mixins that generate css output like gridle, gridle_container, etc...

// your gridle setup section :
@include gridle_setup(());
@include gridle_register_state(mobile, ...);
@include gridle_register_state(tablet, ...);
@include gridle_extend_base_class(...);
@include gridle_apply_css_for(...);

// init the grid here!
@include gridle_init();

// then use your grid as normal
.coco {
    @include gridle(4 push 2);
}
// etc...

Choose a driver

Gridle offer you multiple drivers that you can choose. The default one will make your grid work with float, etc... and the flex one will use flexbox to layout your grid. All this power behind same and simple classes.

// default
@import 'gridle/gridle';

// flex
@import 'gridle/gridle-flex';

States

Gridle includes all you need to generate a fully customizable, responsive grid system.

I have a question about this...

States

Gridle includes all you need to generate a fully customizable, responsive grid system. The principle is a piece of cake. Gridle provides you with a mixin which creates (or registers) "states". States are Gridle's convention that helps you specifically name your responsive breakpoints. Refer to the Gridle state directly within the element's scss rule or by adding auto generated class to the element. Here's how to use states:

Register a State

To register a state, Gridle provides a simple and unique mixin:

@include gridle_register_state ( name , {settings} );
/**
* States are usually initialized with screen sizes :
*/
@include gridle_register_state( mobile , (
    max-width : 400px
) );
@include gridle_register_state( tablet, (
    min-width : 401px,
    max-width : 767px,
    gutter-width : 30px     // change the gutters for this state

    // available options
    // - min-width
    // - max-width
    // - query
    // - gutter-width
    // - gutter-height
    // - gutter-top
    // - gutter-right
    // - gutter-bottom
    // - gutter-left
    // - classes : if need to generate classes
) );

/**
 * States can also be generated without creating classes:
 * Useful when you need a state that cover both the mobile
 * and the tablet for example...
 */
@include gridle_register_state( moblet , (
    min-width : 767px,
    classes : false
) ); 

/**
* State with can also include media queries:
*/
@include gridle_register_state( iphone-landscape , (
    query : "only screen and (max-device-width: ..."
) );

The state can have all the settings available in gridle. If your state doesn't specify gutter width for example, it will default to what has been set in gridle_setup().

Using States

After you have registered you states, the @include gridle_generate_classes() mixin will generate additional classes to be used in your HTML. Here's an example with classes and mixins:

Classes

<div class="container">
    <div class="gr-3 gr-6@tablet gr-12@mobile">
        3 columns, 6 on tablet, 12 on mobile
    </div>
    <div class="gr-12 hide@mobile">
        12 columns but I'm hidden on mobile 
    </div>
</div>

Mixins

/**
* Using mixins :
*/
#content {
    @include gridle( 8 );
    @include gridle_state( mobile ) {
        @include gridle_grid( 8 );
    }

    // or by using gridle_set mixin :
    @include gridle_set ( (
        grid : 8,
        mobile : (
            hide : true
        )
    ) );
}
#sidebar {
    @include gridle( 4 );
    @include gridle_state( mobile ) {
        @include gridle_hide();
    }
}

Register state has to be done before generating classes (cf. Generate Classes Mixin)

Register custom classes

You can also add your own custom class to be created for every state:

@include gridle_generate_custom_class( {pattern} )
// the pattern is a list element or sass
@include gridle_generate_custom_class( ( 'center', '@', '%state' ) ) {
    text-align : center;
}

This will generate the following classes if you have registered the states (mobile, tablet, coco)

.center
.center@mobile
.center@tablet
.center@coco

Make sure to use only the -, --, _, __ or @ as class separators.

Mobile first

Gridle is the perfect fit for your mobile first projects.

I have a question about this...

Mobile First

Gridle is the perfect fit for your mobile first projects. Here how you can start :

Setting up the grid

For mobile first, you have to set the different states for your grid like so

@include gridle_register_state( xs, (
    max-width : 768px
) );
@include gridle_register_state( sm , (
    min-width : 768px
) );
@include gridle_register_state( md, (
    min-width : 992px
) );
@include gridle_register_state( lg, (
    min-width : 1200px
) );

You can use the mixin gridle_register_default_mobile_first_states() that will make this part for you. The values are bases on bootstrap settings

Grid items

Then, you have to tell your grid items to take the full with on small state (if you need so). This is only if you don't want to write each time grid-xs-12 in your html (if your number of columns are 12).

[class*="gr-"] {
    @include gridle_state( xs ) {
        @include gridle_grid( 12 );
    }
}

And your good to go!

When using this, the direction parameter will not have any effect ## Classes

When you're happy with your custom grid system, Gridle will provide you with multiple types of classes. Here's the list:

Container

The container class is not really needed but it's a best practice to wrap all your rows into it so you can define a max-width for your entire grid at once like so

.container
<body>
    <div class="container">
        <div class="row">
            ...
        </div>
    </div>
</div>
// somewhere in your scss
.container {
    max-width: 960px;
    margin: 0 auto;
}

Row

The row class is the one that will wrap all your grid columns.

.row
.row@{state}

// flex driver
.col
.col@{state}
<div class="container">
    <div class="row">
        <div class="gr-6">
            ...
        </div>
        <div class="gr-6">
            ...
        </div>
    </div>
</div>

Row align

Gridle allows you to align your grid elements into a row by setting the alignement class on the row itself like this.

.row-align-left
.row-align-left@{state}
.row-align-center
.row-align-center@{state}
.row-align-middle
.row-align-middle@{state}
.row-align-top
.row-align-top@{state}
.row-align-middle
.row-align-middle@{state}
.row-align-bottom
.row-align-bottom@{state}

// flex driver
.row-align-around
.row-align-around@{state}
.row-align-between
.row-align-between@{state}
<div class="row row-align-middle row-align-center">
    <div class="gr-4">
        I'm the tallest element in the line
        <br />
        cause of this line
        <br />
        and this one...
        <br />
        and this one...
    </div>
    <div class="gr-4">
        I will be vertically centered cause I'm the smallest
    </div>
    <div class="gr-6">
        I will be also vertically centered cause I'm not so tall...
        <br />
        Even with this line...
    </div>
</div>

These classes apply a font-size of 0 on the parent itself and a font-size of 1rem on the direct childs. This is to avoid the display:inline-block space thing... You have to set your font on the html tag for this to work fine...

Row full

This class allows you to make a particular row take the entire screen width without having to close all your container and row elements

.row-full
.row-full@{state}
<div class="container">
    <div class="row">
        <div class="gr-6">
            ...
        </div>
        <div class="gr-6">
            ...
        </div>
    </div>
    <div class="row row-full">
        <div class="gr-4">
            ...
        </div>
        <div class="gr-4">
            ...
        </div>
        <div class="gr-4">
            ...
        </div>
    </div>
</div>

Row reverse (flex driver)

This class allows you to reverse the order of your grid items. This work for the flex driver

.row-reverse
.row-reverse@{state}
<div class="row row-reverse">
    <div class="gr-4">
        I will be displayed as the last item
    </div>
    <div class="gr-4">
        I will be displayed as the second item
    </div>
    <div class="gr-4">
        I will be displayed as the first item
    </div>
</div>

Grid

These are your actual grid columns.

.gr-{columns-count}
.gr-{columns-count}@{state}
<div class="row">
    <div class="gr-8">
        I make 8 columns width
    </div>
    <div class="gr-4">
        I make 4 columns width
    </div>
</div>

Grid adapt / grow

This class allows you to tell a grid column to adapt his width depending on his content

.gr-adapt
.gr-adapt@{state}
.gr-grow
.gr-grow@{state}
<div class="row nowrap wrap@mobile">
    <div class="gr-adapt gr-12@mobile">
        <img src="..." />
    </div>
    <div class="gr-grow gr-12@mobile">
        I will grow to take all the remaining space
    </div>
</div>

<!-- default driver hack only -->
<div class="row nowrap wrap@mobile">
    <div class="gr-adapt gr-6@mobile">
        <img src="..." />
    </div>
    <div class="gr-5 gr-table gr-6@mobile">
        I have the gr-table class to fix display issue
    </div>
    <div class="gr-grow gr-12@mobile">
        I will grow to take all the remaining space
    </div>
</div>

Note the nowrap class on the row that tell the grid to not allow for content to go on a new line and the wrap@mobile class that allow the content have line break as wanted

Grid centered

This class has to be applied on a gr-x element and will center the column.

.gr-centered
.gr-centered@{state}
<div class="row">
    <div class="gr-8 gr-centered">
        This column will be centered
    </div>
    <div class="gr-8 gr-centered@tablet">
        This column will be centered only on tablet
    </div>
</div>

Grid order (flex driver)

These classes will allows you to reorder your grid items. If you have setup your grid with 12 columns, you will have 12 classes like gr-order-1, gr-order-2, ..., gr-order-12.

.order-{columns-count}
.order-{columns-count}@{state}
.order-first
.order-first@{state}
.order-last
.order-last@{state}
<div class="row">
    <div class="gr-6 order-last">
        I will be the last displayed
    </div>
    <div class="gr-3 order-1">
        I will be the first displayed
    </div>
    <div class="gr-3">
        I will be the second displayed
    </div>
</div>

Push & Pull

The push and pull classes are used to offset the grid's elements or even swap two of them for SEO purposes. The HTML structure will not be altered.

.push-{columns-count}
.push-{columns-count}@{state}
.pull-{columns-count}
.pull-{columns-count}@{state}
<div class="row">
    <div class="gr-8 push-4">
        I make 8 columns width and offset 4 columns to the right
    </div>
    <div class="gr-4 pull-9">
        I make 4 columns width and offset 8 columns to the left
    </div>
</div>

Prefix & Suffix

The prefix and suffix classes are used to create blanks before or after a grid element.

.prefix-{columns-count}
.prefix-{columns-count}@{state}
.suffix-{columns-count}
.suffix-{columns-count}@{state}
<div class="row">
    <div class="gr-8 suffix-2">
        I make 8 columns width and I have 2 columns of dead space to my right
    </div>
    <div class="gr-4 prefix-2">
        I make 4 columns width and I have 2 columns of dead space to my left
    </div>
</div>

Wrap / nowrap

This classes are useful to specify on a wrapper that the direct children can or cannot wrap themselves

.wrap
.wrap@{state}
.nowrap
.nowrap@{state}
<div class="row nowrap wrap@mobile">
    <div class="gr-adapt gr-12@mobile">
        ...
    </div>
    <div class="gr-grow gr-12@mobile">
        ...
    </div>
</div>

Clear Each (default driver)

This mixin will make all the {x}n+1 direct child clear itself automatically.

.clear-each-{x}
.clear-each-{x}@{state}
<div class="row clear-each-2">
    <div class="gr-6">
        I'm a content
    </div>
    <div class="gr-6">
        I'm a content
    </div>
    <div class="gr-6">
        I'm a content
    </div>
    <div class="gr-6">
        I'm a content
    </div>
</div>

In order to have these classes, you need to register them before like so :

@include gridle_register_clear_each( {clearEach} , {clearWhat} : both );
// in your _settings.scss file
@include gridle_register_clear_each(2, both);
@include gridle_register_clear_each(3, left);

Hide, show, ...

These classes are used to hide, show or set to “visibility" to some elements for certain states (cf. States)

.hide
.show
.show-inline
.not-visible
.visible
.hide@{state}
.show@{state}
.show-inline@{state}
.not-visible@{state}
.visible@{state}
<div class="row">
    <div class="gr-8 hide@tablet">
        I'm not display (display:none) on "tablet" state
    </div>
    <div class="gr-4 not-visible@mobile">
        I'm not visible (visibility:hidden) on "mobile" state
    </div>
    <div class="gr-12 hide visible@mobile">
        I'm hided by default but displayed on mobile
    </div>
</div>

Float

These classes are used to make float some elements for certain states (cf. States)

.float-left
.float-right
.float-left@{state}
.float-right@{state}
<div class="row">
    <div class="gr-8 float-right float-left@mobile">
        I'm a div that float right normally, but left on mobile
    </div>
</div>

Clear

These classes are used to clear float on some elements for certain states (cf. States)

.clear
.clear-left
.clear-right
.clear@{state}
.clear-left@{state}
.clear-right@{state}
<div class="row">
    <div class="gr-8 clear-right clear-left@mobile">
        I'm a div that clear right normally, but left on mobile
    </div>
</div>

Gutters

These classes are used to delete the gutters on certain columns for certain states (cf. States)

.no-gutter
.no-gutter-left
.no-gutter-right
.no-gutter-top
.no-gutter-bottom
.no-gutter@{state}
.no-gutter-left@{state}
.no-gutter-right@{state}
.no-gutter-top@{state}
.no-gutter-bottom@{state}

.gutter
.gutter-left
.gutter-right
.gutter-top
.gutter-bottom
.gutter@{state}
.gutter-left@{state}
.gutter-right@{state}
.gutter-top@{state}
.gutter-bottom@{state}
<div class="row">
    <div class="gr-8 no-gutter@mobile">
        No gutters on mobile
    </div>
</div>

Row debug

The debug-row class allows you to display the columns as an overlay.

.row-debug
.row-debug@{state}
<div class="row row-debug">
    ...
</div>

Custom classes

Gridle allows you to generate your own classes available in all the registered states. You can do this like so :

@include gridle_generate_custom_class( {pattern} , {states} );
// generate a custom class for all the states
@include gridle_generate_custom_class( ('txt','-','align','-','center','@','%state') ) {
    text-align: center;
    content : "#{gridle_get_current_state_name()}";
}

This will generate all these classes for you if your registered states are mobile and tablet :

.txt-align-center
.txt-align-center@mobile
.txt-align-center@tablet

Mixins

Gridle offer a bunch of usefull SASS mixins to apply grid specific CSS to your custom html tags. All the classes described in the Classes section can be replaced by mixins of this section.

Container

The container mixin just set a clearfix to avoid you any problem to the display

@include gridle_container();
.container {
    @include gridle_container();
    max-width: 960px;
    margin: 0 auto;
}

Row

The row mixin need to be applied on the elements that will contains your columns items

// default driver :
@include gridle_row();

// flex driver :
@include gridle_row( {reverse} ); // true or false

with context :
@include gridle_state( mobile ) {
    @include gridle_row();
}

gridle_set :
@include gridle_set ( (
    row : true
) );    
.my-row {
    @include gridle_row();
}

Row align

This mixin is used to align your grid items in your row.

// possible values :
$align : top | middle | bottom || left | center | right;

@include gridle_row_align ( {align} );

// with state
@include gridle_state ( mobile ) {
    @include gridle_row_align ( {align} );
}

// gridle_set :
@include gridle_set ( (
    row-align : {align}
) );
.my-row {
    @include gridle_row();
    @include gridle_align ( center middle );
}

Row full

This mixin allows you to make a particular row take the entire screen width without having to close all your container and row elements

@include gridle_row_full();

// with state
@include gridle_state ( mobile ) {
    @include gridle_row_full();
}

// gridle_set :
@include gridle_set ( (
    row-full : true
) );

Grid

These are your actual grid columns.

// $column-number : 1...{context} | adapt | grow;

@include gridle_grid ( { column-number} ); 

with context :
@include gridle_state ( mobile ) {
    @include gridle ( {column-number} ); 
}

gridle_set :
@include gridle_set((
    grid : {columns-number}
) );
.wrapper {
    @include gridle_container ( ); // I'm the container
    max-width : 960px;
    margin : 0 auto;
}
#header {
    @include gridle_grid ( 12 );
}
#content {
    @include gridle_grid ( 8 ); // I made 12 columns width...
    @include gridle_state( mobile tablet ) {
        @include gridle_grid ( 12 ); // ... but 12 columns width on mobile and tablet
    }
}
#sidebar {
    @include gridle_grid ( 4 ); // I made 4 columns width...
    @include gridle_state ( mobile ) {
        @include gridle_grid ( 12 ); // ... but 12 columns width on "mobile"
    }
}
#footer {
    @include gridle_grid ( 12 );
}

Grid adapt / grow

This class allows you to tell a grid column to adapt his width depending on his content

@include gridle_grid_adapt();
// same as @include gridle_grid ( adapt );

@include gridle_grid_grow();
// same as @include gridle_grid ( grow );

// with state
@include gridle_state ( mobile ) {
    @include gridle_grid_adapt();
}

// gridle_set :
@include gridle_set ( (
    grid-adapt : true
    grid : adapt // same as line abow
) );
.my-grid-element {
    @include gridle_grid_adapt();
    @include gridle_grid ( adapt ); // same as line abow
}

Grid centered

This mixin will center your grid element

@include gridle_grid_centered();

// with state
@include gridle_state ( mobile ) {
    @include gridle_grid_centered();
}

// gridle_set :
@include gridle_set ( (
    grid-centered : true
) );

Grid order (flex driver)

This mixin allows you to set where your grid element will be displayed in the row. If you have setup your grid with 12 columns, you will have 12 possibilities to order your element

// possible values
$order : 1...{context} | first | last;

@include gridle_order( {order} );

// with state
@include gridle_state ( mobile ) {
    @include gridle_order ( {order} );
}

// gridle_set :
@include gridle_set( (
    order : {order}
) );

Push & Pull

The push and pull mixins are used to offset the grid elements or event swap 2 of them for SEO purpose. The html structure will not be touched as well

@include gridle_push ( {column-number} ); 
@include gridle_pull ( {column-number} );

// with state
@include gridle_state ( mobile ) {
    @include gridle_push( {column-number} );
}

// gridle_set :
@include gridle_set((
    push : {column-number},
    pull : {column-number}
));
/**
 * This code will visualy swap the 2 columns "content" and "sidebar"
 * The HTML structure is not changed as well
 */
#content {
    @include gridle_grid ( 8 );
    @include gridle_push ( 4 ); // I will be offset by 4 columns on the right
}
#sidebar {
    @include gridle_grid ( 4 );
    @include gridle_pull ( 8 ); // I will be effset 8 columns on the left

}

Prefix & Suffix

The prefix and suffix classes are used to create dead spaces before or after a grid element.

@include gridle_prefix ( {column-number} ); 
@include gridle_suffix ( {column-number} );

// with state
@include gridle_state ( mobile ) {
    @include gridle_prefix( {column-number} );
}

// gridle_set :
@include gridle_set((
    prefix : {column-number},
    suffix : {column-number}
), {state} );
/**
 * This code will generate an "checkerboard" style grid
 */
#box1 {
    @include gridle_grid ( 3 );
    @include gridle_prefix ( 3 ); // 3 columns of dead space to the right
}
#box2 {
    @include gridle_grid ( 3 );
    @include gridle_prefix ( 3 ); // 3 columns of dead space to the right
}
#box3 {
    @include gridle_grid ( 3 );
    @include gridle_suffix ( 3 ); // 3 columns of dead space to the left
}
#box4 {
    @include gridle_grid ( 3 );
    @include gridle_suffix ( 3 ); // 3 columns of dead space to the left
}

Wrap / nowrap

These mixins are useful to specify on a wrapper that the direct children can or cannot wrap themselves

@include gridle_wrap();
@include gridle_nowrap();

// with context
@include gridle_state ( mobile ) {
    @include gridle_wrap();
}

// gridle_set :
@include gridle_set ( (
    wrap : true | false, // if false, will apply nowrap
    nowrap : true | false // if false, will apply wrap
) );
.my-row {
    @include gridle_row();
    @include gridle_nowrap();
}

Clear each (default driver)

This mixin will make all the {x}n+1 direct child clear itself automatically.

@include gridle_clear_each ( {each} , {what} );

// with state
@include gridle_state ( mobile ) {
    @include gridle_clear_each ( {each} , {what} );
}

// gridle_set :
@include gridle_set((
    clear_each : ( {each} , {what} )
), {state} );
#myContentThatHasWeirdHeightChilds {
    @include gridle_clear_each( 2, left );
}

Hide, show, etc...

These mixins are used to hide, show or set visibility to some elements for certain states (cf. States)

@include gridle_hide(); 
@include gridle_show(); 
@include gridle_show_inline(); 
@include gridle_not_visible(); 
@include gridle_visible();

// with state
@include gridle_state ( mobile ) {
    @include gridle_hide();
    // etc...
}

// gridle_set :
@include gridle_set((
    hide : true | false,
    show : true | false,
    show_inline : true | false,
    not_visible : true | false,
    visible : true | false
), {state} );
#sidebar {
    @include gridle ( 4 );
    @include gridle_state ( mobile ) {
        @include gridle_hide (); // Not enough space on mobile so we hide it
    }
}

Float

This mixin is used to make element float left, right or both, like a normal float does, but with state capabilities.

@include gridle_float( {left | right | both} );

// with state
@include gridle_state ( mobile ) {
    @include gridle_float( {left | right | both} );
}

// gridle_set :
@include gridle_set((
    float : {left | right | both}
), {state} );
#sidebar {
    @include gridle_float ( right ); // float right normally...
    @include gridle_state ( mobile ) {
        @include gridle_float ( left ); // ... but left on mobile
    }
}

Clear

This mixin work exactly like the float one, but to clear floats... Pretty simple no?

@include gridle_clear( {left | right | both} );

// with state
@include gridle_state ( mobile ) {
    @include gridle_clear ( {left | right | both} );
}

// gridle_set :
@include gridle_set((
    clear : {left | right | both}
), {state} );
#sidebar {
    @include gridle_clear( right ); // clear right normally...
    @include gridle_state ( mobile ) {
        @include gridle_clear( left ); // ... but left on mobile
    }
}

Gutters

These mixins are available to manage gutter on grid elements. In gridle, the gutters are actually paddings.

@include gridle_gutter( {sides | sizes} ); 
@include gridle_no_gutter( {sides | sizes} );

// with state :
@include gridle_state ( mobile ) {
    @include gridle_gutter ( {sides} );
    // etc...
}

// gridle_set :
@include gridle_set((
    gutter : {sides},
    margin : {sides},
    no_gutter : {sides},
    no_margin : {sides}
) );
#sidebar {
    @include gridle_gutter(); // add padding to left and right

    /**
     * You can specify a list of side as first param :
     * top left right bottom    are supported
     */
    @include gridle_gutter ( top left ); // add gutter to top and left only
}
#content {
    @include gridle_no_gutter(); // remove padding to left and right

    @include gridle_no_gutter ( top left ); // remove gutter to top and left only
}
#sizes-specific {
    // 5px top and bottom, 10px left and right
    @include gridle_gutter(10px 20px);

    // 5px top, 10px right, 15px bottom, 20px left
    @include gridle_gutter(5px 10px 15px 20px);
}

Gridle state

This mixin is really, really, really... I mean REALLY useful. It allows you to write some specific CSS on an element for certain states (cf. States). You can also specify min-width and/or max-width as parameters.

@include gridle_state ( {state} ) { 
    {custom-css} 
} 
@include gridle_state ( {min-width} , {max-width} ) { 
    {custom-css} 
}
#header {
    @include gridle_grid ( 12 );
}
#content {
    @include gridle_grid ( 8 );
}
#sidebar {
    @include gridle_grid ( 4 );

    /* We change the background to yellow and we    
     * add a pink border to the sidebar only on tablet...
     * ... JUST BECAUSE I CAN!
     */
    @include gridle_state ( tablet ) {
        background : yellow;
        border : 1px solid pink;
    }

    /**
     * You can specify multiple states directly width gridle_state :
     * !!! multiple states names are the 1st parameter, so NO comma between them...
     * The states can be within quotes or not...
     */
    @include gridle_state ( mobile tablet ) {
        // ... your custom css here
    }

    /**
     * Even make a custom query
     * When passing a custom map state object, it will be extended with the default
     * settings that you have in your gridle_setup
     * !!! query and (max-width, min-width) cannot be used together...
     */
    @include gridle_state ( (
        query : 'only print'
        // or maybe a max-width : 900px
    ) ) {
        background : red;
    }

}
#footer {
    @include gridle_grid ( 12 );
}

Gridle element queries

Gridle has a support for element queries (Thanks to Marc J Schmidt for his wonderfull work on the "polyfill"). To make your element responsive to his own width, use this mixin as described bellow

@include gridle_eq( {width} );
.component {
    background: yellow;

    @include gridle_eq(+600px) {
        // when the component is 600px and greater
        background: pink;
    }
    @include gridle_eq(-300px) {
        // when the component is 300px and lower
        background: green;
    }
    @include gridle_eq(-100px) {
        // when the component is 100px and lower
        background: black;

        .my-nested-element {
            display: none;
        }
    }
}

The browsers did not support them natively. To use element queries, you need to integrate the gridle-eq.js file.

Gridle set

Sometime you want to apply more than one mixin on your item. This can be a pain to write multiple times @include gridle_... You have now this mixin to help you with this.

@include gridle_set( {settings} , {state} );
#myCoolSidebar {

    /**
     * Default usage :
     */
    // set the default values
    @include gridle_set( (
        grid : 4,
        push : 8
    ) );

    // erase values for tablet
    @include gridle_set( (
        grid : 12,
        push : 0
    ), tablet );
    // you can also pass ( tablet, mobile ) as {state} param to apply to multiple states at once

    // hide on mobile :
    @include gridle_hide( mobile );

    /**
     * ------------------ OR --------------------
     */

    /**
     * Or pass your states directly in one gridle_set call :
     * !!! do not set any state as second parameter with this solution
     * Be careful to not have any states that match a reserved gridle setting name like push, pull, etc...
     */
    @include gridle_set( (
        grid : 4,
        push : 8,
        tablet : (
            grid : 12,
            push : 0
        )
    ) );
}

Generate Classes

This mixin is used to generate all the needed classes for your grid system. This mixin is quite modular and allows you to generate all the classes, or if you need, only the classes of a particular state, or only the push and pull classes, etc...

@include gridle_generate_classes ( ); 
@include gridle_generate_classes ( {states} );
@include gridle_generate_classes ( {states} , {what} );
@include gridle_generate_classes ( {states} , {what} , {scope} );
/**
* Setting up your grid :
*/
@include gridle_setup( (
    context : 12,
    gutter-width : 20px
) );

/**
* Register your states if needed :
*/
@include gridle_register_state ( mobile , (
    max-width : 500px
) );

/**
* Generate all the classes :
*/
@include gridle_generate_classes ( );

/**
 * Generate only the classes of the state mobile
 */
@include gridle_generate_classes( mobile );

/**
 * Generate only the push and pull classes of the default state
 * Note that the what parameter is a list
 */
@include gridle_generate_classes( default, push pull );

/**
 * Generate all the classes without the visible and hide package
 */
@include gridle_generate_classes( all , -visible -hide );

If you generate classes for a large grid with multiple states and a lot of columns, I encourage you to make a separated SASS file that contains the grid system only. This will prevent all the classes to be calculated each time you save your working file.

The what parameter

The parameter {what} can be very useful. It allows you to specify witch classes you want to generate. Here's a list of available values that you can use :

// packages :
default     : all the default classes listed bellow
helpers     : all the helpers classes listed bellow
debug       : all the debug classes listed bellow

// default :
container   : the container classes
row         : the row classes
row-align   : all the row-align-... classes
col         : the col classes
row-full    : the row-full classes
nowrap      : the nowrap classes
wrap        : the wrap classes
grid        : all the gr- classes
grid-table  : the grid-table classes
grid-grow   : the grid-grow classes
grid-adapt  : the grid-adapt classes
grid-centered : the grid-centered classes
push        : all the push- classes
pull        : all the pull-classes
prefix      : all the prefix- classes
suffix      : all the suffix- classes

// helpers :
float       : all the float- classes
clear       : all the clear- classes
gutter      : all the gutter- classes
no-gutter   : all the no-gutter- classes
hide        : all the hide- classes
show        : all the show- classes
show-inline : all the show-inline- classes
not-visible : all the not-visible- classes
visible     : all the visible- classes
clear-each  : all the clear-each- classes
order       : all the order classes

// debug
row-debug   : the row-debug classes

Selector

If needed, you can apply some css to specifiy gridle selectors. This can be useful if you cannot target some grid elements by using something like [class*="gr-"]...

@include gridle_selector( {packages} , {states} ) {
    // your custom css here...
}
@include gridle_selector(grid grid-grow grid-adapt) {
    content : "I will target all the grid, grid-grow and grid-adapt elements of all states";
}

@include gridle_selector(grid, mobile) {
    content : "I will target all the grid elements of the mobile state"
}

What is the context ?

The context is the number of columns in your grid used to calculate the widths. By default, if not specified in the mixins that support the context, it will be equal as the $gridle-columns-count configuration.

For example, if your configuration is set to $gridle-columns-count : 12; and that you do @include gridle( 6 );, this will set your width to *100% / 12 6 = 50%**

If you set the context like so @include gridle( 6 , 10 );, even if your configuration is $gridle-columns-count : 12; , the width will be set to *100% / 10 6 = 60%**

Functions

Gridle offer a bunch of usefull SASS functions that you can use.

gridle_states_count

Return the number of states registered

gridle_states_count();
$count : gridle_states_count();

gridle_current_state

Return the current state map depending in witch gridle_state you are

gridle_current_state();
$state : gridle_current_state(); // will return the default state

@include gridle_state( mobile ) {
    $state : gridle_current_state(); // will return the mobile state
}

gridle_current_state_name

Return the current state name depending in witch gridle_state you are

gridle_current_state_name();
$name : gridle_current_state_name(); // will return default

.my-cool-element {
    @include gridle_state( mobile tablet ) {
        $name : gridle_current_state_name(); // will return once mobile and once tablet
        content : #{$name};
    }
}

gridle_column_width

Return the width in percentage of one/more column(s)

gridle_column_width();
gridle_column_width( {columns} );
gridle_column_width( {columns} , {state} );
$width-of-1-column : gridle_column_width();
$width-of-3-columns : gridle_column_width( 3 );
$width-of-1-column-in-mobile : gridle_column_width( 1, mobile );

gridle_get_state

Return the state map

gridle_get_state();
gridle_get_state( {state} );
$defaultState : gridle_get_state();
$mobileState : gridle_get_state( mobile );

#mobileState {
    content: inspect(gridle_get_state( mobile ));
}

gridle_has_state

Return if a state with the passed name exist

gridle_has_state( {state} );
@if gridle_has_state( mobile ) {
    // do something...
}

gridle_get_state_var

Return a state var value. If no state is provided, will return the var of the current state

gridle_get_state_var( {varName} );
gridle_get_state_var( {varName} , {state} );
$default-state-context : gridle_get_state_var( context );
$mobile-state-gutter-width : gridle_get_state_var( gutter-width , mobile );

.my-cool-item {
    @include gridle_state ( mobile ) {
        content : #{gridle_get_state_var(name)}; // will output mobile
    }
}

Here's a list of all the variables you can get :

- name
- min-width
- max-width
- query
- classes // true or false if the classes need to be generated for this state
- context
- gutter-width
- gutter-height
- gutter-top
- gutter-right
- gutter-bottom
- gutter-left
- direction
- name-multiplicator
- states-classes // true or false if need to generate the states-classes

gridle_get_states_names

Return a list of all the states names registered

gridle_get_states_names();
$statesNames : gridle_get_states_names();
@each $name in $statesNames {
    // do something here...
}

gridle_get_driver

Return the current driver used like default or flex...

gridle_get_driver();
$driver : gridle_get_driver();
@if $driver == flex {
    // do something...
}

gridle_is_driver

Return true of false depending if the specified driver is the current one

gridle_is_driver( {drivers} );
@if gridle_is_driver( flex coco ) {
    // do something when the used driver is flex or coco
}

gridle_get_media_query

Return the media query of the specified state or the current one

gridle_get_media_query();
gridle_get_media_query( {state} );
.my-cool-element {
    content : #{gridle_get_media_query()};

    @include gridle_state(mobile) {
        content : #{gridle_get_media_query()};
    }
}

Advanced Settings

Here's some advanced options to customize a little more your grid

Custom column

Gridle will generate for you all the columns you need, depending on the context setting. That's fine. But sometime, you need some special columns... For example, a column of 33.333%, or 66.6667%, etc... This setting is made for you.

@include gridle_register_column( {name} , {column-count} , {context} );
/**
 * Here we register a column with the ratio 1/3
 * where the "1" is the column-count, and the "3" is the context
 * in witch the column width will be calculated
 */
@include gridle_register_column( 1on3 , 1, 3 );

// another fancy example :
@include gridle_register_column( myFancyColumn , 12, 33 ); // 36.36%

States classes

This option allow you to generate all the classes scoped in a .state-{state} class. This allows you to view your grid by applying the name of your state as class on an html tag without needing the media queries. This is more a debug option that a real production one...

@include gridle_setup( (
    context : 12,
    // etx...
    states-classes : true // activate the behavior
) );

Then :

<html class="state-mobile">
    <!-- this will activate the mobile state -->

Generate JSON settings (for gridle.js)

This options allow you to enable / disable the generation of JSON settings in the css. This JSON is needed if you want to use gridle.js

$gridle-generate-json-settings : false; // default is true

Classes prefix

This option allow you to specify a prefix that will be added at all the gridle generate classes.

@gridle_setup( (
    // your settings...
    classes-prefix : 'hello-'
) );
<div class="hello-row">
    <div class="hello-gr-2 hello-push-5 hello-hide@mobile">
        ... All the classes will be affected ...
    </div>
</div>

Classes names

These options are quite advanced stuffs but can be usefull if you want to customize the generated class names exactly as you want. Each pattern define how the classname will be generated. These are the tokens that you can use in the patterns :

%state      : Represent the state name (mobile, coco, etc...)
%column     : Represent the column index (1, 2, 10, etc...)  
%reverse    : Represent the "reverse" keyword in some patterns
%align      : Represent the alignement like "center", "middle", etc...
%float      : Represent the float like "left", "right" and "both"
%count      : Used in some patterns to represent a number
%side       : Reprensent a side for gutters like "top", "bottom", "left" and "right"
%column-count   : Represent the column number in the order class

To see the default patterns, I let you check the _settings.scss file in the gridle folder

If you want to customize a pattern, you just have to use the gridle_set_classname_map mixin like so :

@include gridle_set_classname_map ( {package}, {pattern} );

Note that the {package} parameter is the index of each map elements in the _settings.scss file like "clear-each", "grid", etc...

Extend base classes

You can extend the base gridle classes by using the mixin bellow. This has to be used with caution only if you now what you are doing...

@include gridle_extend_base_class( {packages} , {css_map} , {states} );
// add some css to the grid classes
@include gridle_extend_base_class(grid, (
    content : "I will be applied on all the grid classes in all the states"
));

// add some css only to the mobile state, grid and push classes
@include gridle_extend_base_class(grid push, (
    content : "I will be applied on all the grid and push classes of mobile state"
), mobile);

Apply css for all classes in some states

This mixin seams to be the same as the gridle_extend_base_class one. The big difference it that by using this, you tell to apply some css for all the specified package and all the states when the active state is the specified one.

@include gridle_apply_css_for( {packages} , {css_map} , {states} );
// apply this css when the active state is mobile on all the grids
@include gridle_apply_css_for(grid grid-grow grid-adapt, (
    content : "I will be applied on all the grids when the active state is mobile"
), mobile);

You can use this if you really need that particular behavior. Otherwise, it's more efficient to use something like this :

[class*="gr-"] {
    @include gridle_state(mobile) {
        content : "do something...";
    }
}

Gridle js

Gridle js is a little file that allows you to be notified when your page change of states, witch state is active, witch not, and witch states have changed.

I have a question about this...

Gridle JS (1.0)

Gridle js is a little file that allows you to be notified when your page change of states, witch state is active, witch not, and witch states have changed. All of this with a simple syntax.

Installation

Gridle.js is part of the package that you get from github or bower. To install it, simply reference the gridle.js in your html file like so :

<head>
    <!-- ... -->
    <script src=".../gridle.js"></script>

    <!-- if need element-queries support -->
    <script src=".../gridle-eq.js"></script>
    <!-- ... -->
</head>

Setup

This part is optional but is you want to configure the plugin, you will need to do this

Gridle.init ( {settings} );

These are the options available

Gridle.init({

    // make gridle output some console.log
    debug : true,

    // callback when the states changes
    onUpdate : function(updatedStates, activeStates, inactiveStates) {
        // do something here...
    }

});

API

Gridle.js provide a simple and clean API.

on

This method allows you to subscribe to an event emited by Gridle.js

Gridle.on('update', function(updatedStates, activeStates, inactiveStates) {
    // do something here
});

isReady

This method allows you to check if gridle is ready. This mean that it has finded the states in your css.

if ( Gridle.isReady() ) {
    // do something here...
}

isActive

This method allows you to check if a state is active

if ( Gridle.isActive('mobile') ) {
    console.log('mobile state is active');
}

getDefaultState

This method allows you to get the default state

var defaultState = Gridle.getDefaultState();

getRegistredStates

This method allows you to get all the registered states

var states = Gridle.getRegisteredStates();

getUpdatedStates

This method allows you to get all updated states. Be careful, this will be available only when the states change, then, when the screen is resized and the states are the same, this will be empty...

var states = Gridle.getUpdatedStates();

getUpdatedStatesNames

Same as getUpdatedStates, but return an array of names only

var states = Gridle.getUpdatedStatesNames();

getActiveStates

Allows you to get the active states

var states = Gridle.getActiveStates();

getActiveStatesNames

Same as getActiveStates, but return an array of names only

var states = Gridle.getActiveStatesNames();

getInactiveStates

Allows you to get the unactive states

var states = Gridle.getInactiveStates();

getInactiveStatesNames

Same as getUnactiveStates, but return an array of names only

var states = Gridle.getInactiveStatesNames();

Events

Gridle js trigger some events to be notified of states change, etc... Here's a list

ready

This event notify that gridle has find the states in css and is ready to check changes

update

This event is the main one. It notifies you that some states have changed.

Subscribe to an event

The events in gridle.js are emitted through multiple channel. jQuery events are supported and you can also use the simple built-in event function to subscribe to an event. Here's how :

Built-in

Gridle.on('update', function(updatedStates, activeStates, inactiveStates) {
    // do something here... 
});

jQuery

By using jQuery, you can either subscribe directly on the Gridle object, or through the "body" DOM node

// directly on Gridle :
jQuery(Gridle).bind('update', function(updatedStates, activeStates, inactiveStates) {
    // do something here... 
});

// through the body node :
jQuery('body').trigger('gridle.update', function(updatedStates, activeStates, inactiveStates) {
    // do something here... 
});

Be careful, when listen for event through the body tag, the event name will be prefixed by "gridle.". For example, update will become "gridle.update"

Element queries support

Gridle support element queries but for now, the browsers did not support them natively. To use element queries, you need to integrate the gridle-eq.js file.

Element queries "polyfill" is provided by Marc J Schmidt. Thanks a lot to him for his wonderfull work! You can integrate his polyfill instead of using the gridle-eq.js file if you prefer.

Changelog

Here what has changed in this version.

I have a question about this...

Changelog

Here what has changed in this version

2.0.3

Fix some issues with nesting grids

Your grid will now have the full container width available cause all the rows will expand themselves by the gutter width. This is a better behavior.

Adding license in repo

There's now a LICENSE.txt file in the repo.

Adding basic mixins sample in demo-mixins.html file

2.0.2

Adding element queries support

You have now support for element queries.

2.0.0

Nested grid : no more parent class and mixin

To handle the nested grids, previous version had a parent class. This is no more needed.

row class

The new row class is at some point a replacement for the parent one. This class has to wrap each "lines" of columns. You will have more control over your columns alignement, etc...

grid-... classes became gr-...

The grid-... classes has now became gr-... . It's 2 letters I know but this mean a lot in a large project...

@ in classnames

Now all of the grid classes stay in the same format. To scope a class in a particular state, just add @{stateName} at the end of your classname.

Feature : gr-grow, gr-adapt

The all new gr-grow and gr-adapt classes allows you to create columns that will behave dpending of the column content instead of a specific width.

Feature : row-align-...

The all new row-align-... classes allows you to align your columns as you want (top, middle, bottom, left, center, right).

Flex support

Gridle has now a full flex version. To use this version, check out the driver section on the documentation. Some features are only available in a specific driver

Drivers

Gridle has now multiple drivers that you can use to generate your grid. For now the default and the flex driver are available. Some features are only available in a specific driver (cf. documentation).

New wrap / nowrap classes

These classes are useful in conjunction with the gr-adapt and gr-grow to handle complexe layouts.

Row full class

The new row-full class allows you to make a row take the entire screen width.

Flex : order

Some new classes to order your columns

No more nested gridle mixin in gridle_state issue

You can now nest your gridle_... mixins in a gridle_state one

Some new functions

Some new functions have been added to the api (cd. documentation)

Change comment style to //

Update all comments to avoid comments in generated css

Stay in touch

Don't miss anything new about gridle, updates, etc... You will not be spammed don't worry

Fork me on GitHub