postcss-assemble-grid

v1.0.0

Published

2 years ago

A PostCSS plugin for easily creating flexbox grids.

Downloads

0High
0Medium
0Low

lukelarsen

postcss css postcss-plugin grid grids flexbox

PostCSS Assemble Grid

PostCSS plugin for easily creating flexbox grids.

Example

<body>
    <div class="frame">
        <div class="frame-cell  frame-cell--sidebar">
            <div class="sidebar">
                Sidebar
            </div>
        </div>
        <div class="frame-cell">
            <div class="grid">
                <div class="grid__cell">
                    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Est fugiat, nam odit incidunt ab vitae explicabo hic, placeat, aliquid dolorem nisi quisquam omnis nulla eum maxime ipsum magnam non. Nam.</p>
                </div>
                <div class="grid__cell">
                    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Corrupti harum quia nostrum laboriosam perferendis quos aliquid quae voluptate cupiditate sed! Quaerat nisi voluptatem corporis expedita similique placeat itaque voluptatibus eum?</p>
                </div>
                <div class="grid__cell  grid__cell--half">
                    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Pariatur autem magnam illum amet odit quasi dolore. Vero reprehenderit odit magni, quis totam aut officiis dignissimos ad, ut minus dicta perspiciatis.</p>
                </div>
                <div class="grid__cell">
                    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Adipisci eos optio ea maxime illum facilis rerum non ex tempora, voluptatem excepturi, in deserunt repellat nostrum distinctio praesentium tempore porro quam.</p>
                </div>
                <div class="grid__cell">
                    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Est fugiat, nam odit incidunt ab vitae explicabo hic, placeat, aliquid dolorem nisi quisquam omnis nulla eum maxime ipsum magnam non. Nam.</p>
                </div>
                <div class="grid__cell">
                    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Corrupti harum quia nostrum laboriosam perferendis quos aliquid quae voluptate cupiditate sed! Quaerat nisi voluptatem corporis expedita similique placeat itaque voluptatibus eum?</p>
                </div>
                <div class="grid__cell">
                    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Pariatur autem magnam illum amet odit quasi dolore. Vero reprehenderit odit magni, quis totam aut officiis dignissimos ad, ut minus dicta perspiciatis.</p>
                </div>
                <div class="grid__cell">
                    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Adipisci eos optio ea maxime illum facilis rerum non ex tempora, voluptatem excepturi, in deserunt repellat nostrum distinctio praesentium tempore porro quam.</p>
                </div>
            </div>
        </div>
    </div>
</body>

/* For example only. */
body{
    margin: 0;
    padding: 0;
}

/* Using border-box on the grid is required.
   You don't have to apply it to everything.
   You could just apply it to the grid markup. */
*,
*:before,
*:after {
    box-sizing: border-box;
}

/* Plugin Usage */
.frame{
    assemble-grid: fit 30px;
}

.frame-cell--sidebar{
    assemble-cell: 350px;
}

.grid{
    assemble-grid: 1/4 30px;
}

@media all and (max-width: 750px) and (min-width: 200px) {
    .grid{
        assemble-mq-grid: 1/1 20px;
    }
}

.grid__cell--half{
    assemble-cell: 1/2 bottom;
}

/* For example only. */
.sidebar{
    width: 100%;
    background-color: red;
}

.grid__cell p{
    margin: 0;
    background-color: blue;
}

Will output:

/* For example only. */
body{
    margin: 0;
    padding: 0;
}

/* Using border-box on the grid is required.
   You don't have to apply it to everything.
   You could just apply it to the grid markup. */
*,
*:before,
*:after {
    box-sizing: border-box;
}

/* Plugin Usage */
.frame{
    display: flex;
    margin: 0;
    padding: 0;
    list-style: none;
    flex-wrap: wrap;
    margin-left: -30px;
}
.frame > *{
    display: flex;
    flex: 1;
    margin-bottom: 30px;
    padding-left: 30px;
}

.frame-cell--sidebar{
    flex: 0 0 350px;
}

.grid{
    display: flex;
    margin: 0;
    padding: 0;
    list-style: none;
    flex-wrap: wrap;
    margin-left: -30px;
}

.grid > *{
    display: flex;
    flex: 0 0 25%;
    margin-bottom: 30px;
    padding-left: 30px;
}

@media all and (max-width: 750px) and (min-width: 200px) {
    .grid{
        margin-left: -20px;
    }
    .grid > *{
        flex: 0 0 100% !important;
        margin-bottom: 20px;
        padding-left: 20px;
    }
}

.grid__cell--half{
    flex: 0 0 50%;
    align-self: flex-end;
}

/* For example only. */
.sidebar{
    width: 100%;
    background-color: red;
}

.grid__cell p{
    margin: 0;
    background-color: blue;
}

Demo

Usage

npm install postcss-assemble-grid --save-dev

Gulp

var postcss = require('gulp-postcss');
var assembleGrid = require('postcss-assemble-grid');

gulp.task('css', function () {
    var processors = [
        assembleGrid
    ];
    return gulp.src('./src/*.css')
        .pipe(postcss(processors))
        .pipe(gulp.dest('./dest'));
});

Requirements

The use of Assemble Grid requires that box-sizing: border-box; be set on the grid cells. It is common to just apply this to everything with:

*,
*:before,
*:after {
    box-sizing: border-box;
}

You can apply it to only the grid if you don't want to apply it to everything in your project. You do this by setting the box-sizing option to true when using assemble-grid: See more information under 'Options'.

.grid{
    assemble-grid: 1/4 30px _ _ true;
}

Options

assemble-grid

assemble-grid will set options for all the cells in a grid at once. It should always be used when using Assemble Grid. It builds the base for your grid. Options for 'assemble-grid' are as follows: assemble-grid: Cell Width, Gutter Width, Grid Width/Center, Cell Alignment, Box Sizing

Cell Width (required)

This will set the width of all the cells in your grid. Cell Width can be any of the following:

Fraction (ex. 1/4)
Number Value (ex. 320px)
'fit' (This will fit all cells in a single row.)

Gutter Width (optional)

This will set the size of the gutters in your grid. Gutter Width can only be:

Number Value (ex 30px)

Grid Width/Center (optional)

This will give the grid a set width and center it. Grid Width/Center can only be:

Number Value (ex 850px)

Cell Alignment (optional)

This will set the alignment of each cell in the grid. Cell Alignment can be any of the following:

top
bottom
center

Box Sizing (optional)

This will add the needed box-sizing: border-box; to each grid cell. Many people prefer this to be included on everyhting with *. If you do not use this on everything you must set this to true. Box Sizing can be:

true
false

Not setting some options

If you would like to set an option but leave the option before it blank you can do so like this: assemble-grid: 1/4 _ 800px; This would set a grid cell width of 25%, no gutters (the '_'), and a fixed grid width of 800px.

assemble-cell

assemble-cell will allow you to change the behavior of a single grid cell. Let's say you used assemble-grid like this:

.grid{
    assemble-grid: 1/4 30px;
}

This makes all the cells in your grid 25% with 30px gutters. Now lets say you want one cell in that grid to be 1/2. On that cell add this:

.grid-cell{
    assemble-cell: 1/2;
}

This would override the 25% declaration from assemble-grid and make just this cell 50%.

Options for 'assemble-cell' are as follows: assemble-cell: Cell Width, Cell Alignment

Cell Width (optional)

This will set the width of only this cell. Cell Width can be any of the following:

Fraction (ex. 1/4)
Number Value (ex. 320px)

Cell Alignment (optional)

This will set the alignment of only this cell. Cell Alignment can be any of the following:

top
bottom
center

Both are optional?

Yes, both are optional but you will need at least one of these options when using assemble-cell.

assemble-mq-grid

Using assemble-mq-grid is for when you need to change the behavior of a grid in a media query. Instead of re-writing all the css for the grid we only override the parts that need changing. Assemble Grid leaves defining the media queries up to you. A great plugin for this is PostCSS Custom Media. After you have defined a media query you can use it like this:

@media all and (max-width: 1000px) and (min-width: 700px) {
    .grid{
        assemble-mq-grid: 1/2 20px;
    }
}

This would change the grid to have 50% cell widths and 20px gutters within the given media query.

Options for 'assemble-mq-grid' are as follows: assemble-mq-grid: Cell Width, Gutter Width, Grid Width/Center, Cell Alignment

Cell Width (optional)

This will set the width of all the cells in your grid. Cell Width can be any of the following:

Fraction (ex. 1/4)
Number Value (ex. 320px)
'fit' (This will fit all cells in a single row.)

Gutter Width (optional)

This will set the size of the gutters in your grid. Gutter Width can only be:

Number Value (ex 30px)

Grid Width/Center (optional)

This will give the grid a set width and center it. Grid Width/Center can only be:

Number Value (ex 850px)

Cell Alignment (optional)

This will set the alignment of each cell in the grid. Cell Alignment can be an of the following:

top
bottom
center

Everything is optional?

Yes, everything is optional but you will need at least one of these options when using assemble-mq-grid.

What about assemble-mq-cell?

What if you want to modifiy a single cell in a media query? When modifing a single cell have to override everything that assemble-cell generates so there is no need for a assemble-mq-cell. Just use assemble-cell within a media query and you are good to go.

Nesting

Nesting just works. You can next as many grids as you want. With a lot of grid systems you have to nest to achieve what you can probably do with assemble-cell. Check to see if you can accomplish what you need with asseble-cell before you start nesting. To nest you just need to place another assemble-grid inside a single cell.

Extra Info

While not a requirement it is recommended that when you are creating markup for your grids you only apply assemble-grid, assemble-cell, and assemble-mq-grid to a specific html tag. If you need to add style, such as background-color (or anything else), you should do that on a differnt tag withing your grid markup. This will help keep things organized and allow you to re-use your gird classes with out visual style getting in the way. Again, this is just advice. It is not required.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

PostCSS Assemble Grid

Example

Usage

Gulp

Requirements

Options

assemble-grid

Cell Width (required)

Gutter Width (optional)

Grid Width/Center (optional)

Cell Alignment (optional)

Box Sizing (optional)

Not setting some options

assemble-cell

Cell Width (optional)

Cell Alignment (optional)

Both are optional?

assemble-mq-grid

Cell Width (optional)

Gutter Width (optional)

Grid Width/Center (optional)

Cell Alignment (optional)

Everything is optional?

What about assemble-mq-cell?

Nesting

Extra Info