Grid Layout

Add the .layout-grid or .layout-inline-grid classes to create a grid-based layout and turn all children into grid items. We use the grid-template-columns and grid-template-rows CSS properties to set up the grid, and the grid-column and grid-row properties to set the dimensions of the grid items

We do not cover grid-template-areas or grid-area. An area-based grid requires a different, specific author-declared syntax that cannot be automated through CSS utility classes.
The implicit widths and heights of grid columns and grid rows must be defined by the author by declaring grid-auto-columns and grid-auto-rows and can likewise not be automated by our grid utility classes.

You can modify the spacing between grid-items by using our gap utility classes, or by manually defining the CSS gap properties yourself.
Because our grid layouts use fraction units (fr), gaps are taken into account when setting up the grid and will not lead to overflows as with our flex layout.

The grid itself creates 4 CSS custom properties alongside it:

• --_grid-column-layout - The logic used to generate the grid column track sizing. This is minmax(min(var(--_min-col-width, 0px), 100%), var(--_max-col-width, 1fr))' by default. Essentially, this means that:
  • grid-columns will have a minimum size defined by either --_min-col-width, or 100% of the parent grid's width (whichever is smaller, to prevent columns from overflowing out of the grid). If --_min-col-width is not defined by the author, it defaults to 0.
  • grid-columns will have a maximum size defined by --_max-col-width. If --_max-col-width is not defined by the author, it defaults to 1fr.
• --_grid-row-layout - The logic used to generate the explicit grid rows track sizing. This is auto by default, which means grid rows do not follow any specific sizing logic and will simply stretch to fit in the largest item within the row. This is usually the desired behavior because the sizing of grid rows is usually determined by the size of the grid items inside it, and not the width of the viewport as is the case with grid columns.
• --_grid-column-count - The number of explicit columns created by the grid. This is 0 by default, which means all columns generated by the grid use the implicit size defined by grid-auto-columns, if it is declared by the author. If it is not declared, grid items will automatically stretch to fill up the entire column.
• --_grid-row-count - The number of explicit rows created by the grid. This is 0 by default, which means all rows generated by the grid use the implicit size defined by grid-auto-rows, if it is declared by the author. If it is not declared, grid rows will stretch to fit the content of the largest grid item inside the row.

The values of these custom properties are injected into the grid-template-columns and grid-template-rows properties defined by the .layout-grid or .layout-inline-grid classes to set up the grid and its items:

• grid-template-columns: repeat(var(--_grid-column-count), var(--_grid-column-layout));
• grid-template-rows: repeat(var(--_grid-row-count), var(--_grid-row-layout));

note: When nesting grid layouts, you will have to manually re-declare the values of all custom properties, or the nested grid will automatically inherit them from the parent.

Because the values of --_grid-column-count and --_grid-row-count are 0 by default, a basic grid declared by our grid classes will create a fully implicit grid with vertically-stacked items as demonstrated below:

Because all track sizes in an implicit grid are auto-sized by the size of the grid items themselves, it behaves similar to flex layouts with a flex-direction of 'column', which means you can use the justify-content or align-content properties to modify the alignment of the grid items inside the grid. One difference is that grid items will stretch within their respective columns, the size of which is defined by the widest grid item. You can change the alignments of the individual grid items within their respective columns with justify-items or justify-self:

Setting up the number of grid columns / grid rows

To create an explicit grid, you must define the number of columns and/or rows the grid should have by changing the values of --_grid-column-count and/or --_grid-row-count to a positive integer. The easiest way to do this is by setting our responsive .grid-cols and .grid-rows utility classes on the grid, which will modify the values of the custom properties:

By setting grid-cols-2 grid-cols-lg-3 on the grid, we indicate that the number of columns inside grid should be 2 on smaller screens, and 3 on larger screens. The grid items are then placed inside the columns in DOM order. If a 4th grid item is added, it will automatically be placed in a new implicit row (because no explicit rows were declared), but inside the first explicit column.

Our .grid-cols and .grid-rows utility classes are created using a responsive mixin. The number of generated utility classes for the columns and rows is determined by the variables $document-grid-column-count (12 by default) and $document-grid-row-count (6 by default). inside _variables.scss. You can modify the values of these variables as necessary to fit your project, or alternatively, manually declare values for --_grid-column-count and --_grid-row-count using CSS and Media queries.

Changing the position of grid items

Grid items are placed inside a grid in order that they appear in the DOM by default. However, you can change a grid item's starting position inside a grid with the grid-column-start and grid-column-end CSS properties. The easiest way to do this is by setting our responsive .colstart and .rowstart utility classes on the grid item. You can use these utility classes even outside the context of our grid layout.

Note: When (parts of) grid items would otherwise overlap the same column and/or row, grid layouts will automatically move these grid items to the next column/row. You must explicitly declare the same grid-column-start and grid-row-start on both grid items if you want them to overlap.

Like our .grid-cols and .grid-rows utility classes, our .colstart and .rowstart utility classes are generated using a mixin, and use the same SCSS variables to determine the number of classes generated. You can also manually set the grid-column-start and grid-row-start properties using CSS and Media queries.

Changing the size of grid items

Grid items inside an explicit grid, by default, will take up exactly 1 column and 1 row inside the grid, which is the implicit size for a grid item. You can change the number of columns and rows a grid item spans with the grid-column-end and grid-row-end CSS properties. These properties allow you to declare a "span" keyword, followed by an integer. The easiest way to do this is by setting our responsive .colspan and .rowspan utility classes on the grid item. In addition to integers, you can also declare .colspan-end or .rowspan-end to indicate a grid item should always span until the start or end of its current column/row. This does require the grid item to have a specified grid-column-start or grid-row-start value, otherwise the grid item will simply be 'placed' at the end of the column/row, rather than 'stretch' since the implicit grid item sizing is 1 column / 1 row. You can use these utility classes even outside the context of our grid layout.

Like our .grid-cols and .grid-rows utility classes, our .colspan and .rowspan utility classes are generated using a mixin, and use the same SCSS variables to determine the number of classes generated. You can also manually set the grid-column-end and grid-row-end properties using CSS and Media queries.

Setting our .colspan, .rowspan, .colstart and .rowstart utility classes on the children, combined with the .grid-cols and .grid-rows utility classes on the grid allows for a fully-customizable explicit and responsive grid.

Changing the Flow direction

Grid layouts will, by default, place grid items into a row, and then stretch them to fill out a column if there is space. You can override this with our .grid-flow utility classes, or by manually setting grid-auto-flow through CSS. You can declare either a row, column or dense grid layout. Note that this only affects implicitly-generated grid columns / rows. Grid items with an explicit grid column / row are unaffected.

The grid above has no explicit grid-columns or grid-rows. Normally, this would cause a grid to generate implicit grid rows for each grid item, because the default value of grid-auto-flow is 'row'. However, by setting .grid-flow-column, we change the behavior in such a way that the grid will now generate implicit columns for each grid item instead. Because these grid columns are implicitly generated, their size can be modified with grid-auto-columns as well.

The example above shows a grid with 3 explicit grid columns. When a 4th item is added to the grid, it would normally be placed in a new row. However, because grid-auto-flow is set to 'column', it is instead placed in an implicitly-generated grid-column, the sizing of which can be changed by setting grid-auto-columns on the parent grid.

The grid above would normally leave gaps in a row or column-based grid. .grid-flow-dense applies the 'dense' algorithm on the grid, which will attempt to fill the grid with items without leaving empty columns or rows. This is particularly useful when you are working with a type of grid where the order and sizing of grid items is not known in advance (for example, an image gallery with differently-sized thumbnails).

auto-fill and auto-fit grid layouts

Instead of explicitly declaring grid columns using numerical values, you can also choose to create a grid where the number of columns depends on the minimum and maximum permitted column width set by --_min-col-width and --_max-col-width. Assuming a row-based layout, this means the browser will place as many columns next to each other in the same row as possible, without shrinking or growing beyond the permitted values. Should a grid-item's width become smaller than --_min-col-width, it will create space in the row by moving the last item to a new row. This allows for an inertly responsive grid because items will be placed on new rows as necessary as the grid's width changes. The easiest way to declare such a grid is by setting our responsive .grid-cols-auto-fill or .grid-cols-auto-fit utility classes on the grid.

--_min-col-width and --_max-col-width are not particularly useful in grids where the number of columns is explicitly declared, as this will often cause grid items to overflow when they are too wide to fit the number of explicit columns declared per row. For auto-fill and auto-fit grids however, declaring --_min-col-size is crucial to inform the browser how many columns can fit next to each other before it has to move grid items to a new row. You can resize the browser window to see this in action on the grid below:

The choice between auto-fill or auto-fit depends on the situation; auto-fit will cause empty grid columns to collapse and the remaining grid items to fill up the remaining space in the row (unless otherwise specified by --_max-col-width), while auto-fill preserves empty grid cells, even in situations where there are not enough items to fill up all the grid columns that can fit inside a grid row as allowed by --_min-col-width and --_max-col-width. In either situation, setting a minimum column width is recommended so the browsers knows when to move items to the next row and prevent overflowing.

Subgrid

In situations where you want a grid item to inherit the column structure of the parent grid, you can declare the .layout-subgrid class on the grid item. This grid item will then become a grid itself, with an amount of columns equivalent to that of its own colspan, allowing for effective grid nesting without having to set up another grid with new columns:

Changing the alignment of grid items

The justify-content, align-content, justify-items, align-items, justify-self and align-self CSS properties can be used the control the alignment and positioning of grid items inside the grid. Our alignment utility classes for each of these properties offer a responsive, convenient solution to this to limit the amount of custom CSS that has to be written:

• .justify-content controls how grid items are distributed inside the grid's main axis (horizontal by default). Declare on the grid container.
• .align-content controls how grid items are distributed inside the grid's cross axis (vertical by default). Declare on the grid container.
• .justify-items controls how grid items are aligned horizontally inside the grid layout's generated columns. Declare on the grid container.
• .align-items controls how grid items are aligned vertically inside the grid layout's generated columns. Declare on the grid container.
• .justify-self controls how individual grid items are aligned horizontally inside the grid layout's generated column. Takes priority over justify-items. Declare on the grid item.
• .align-self controls how individual grid items are aligned vertically inside the grid layout's generated column. Takes priority over align-items. Declare on the grid item.

You can use our live grid layout generator below to test the effect of these utility classes and their supported values in an actual grid layout.