Skip to main content

Layout

CSS grid

Bootstrap's opt-in CSS Grid system is switched on in this theme — .grid, .g-col-* and .g-start-*.

How it works

Bootstrap 5.1 added a separate grid built on CSS Grid, behind $enable-cssgrid. Stock Bootstrap ships it off. rb-bootstrap compiles with it on, alongside the regular flexbox grid. Use whichever suits the layout; they do not interfere with each other.

  • The parent is .grid, not .row. It sets display: grid with twelve equal template columns and a gap.
  • Children are .g-col-*, not .col-*. .g-col-4 spans four template columns. Responsive infixes work as usual: .g-col-md-6.
  • Placement uses .g-start-*. Instead of offsets, set the start line (1–11).
  • Everything else is a CSS variable. --bs-columns, --bs-rows and --bs-gap on .grid change the template without a recompile.
.grid {
  display: grid;
  grid-template-rows: repeat(var(--bs-rows, 1), 1fr);
  grid-template-columns: repeat(var(--bs-columns, 12), 1fr);
  gap: var(--bs-gap, 1.5rem);
}

Key differences

Compared to the default grid system:

  • Flex utilities do not affect the CSS Grid columns in the same way.
  • Gaps replace gutters. The gap property replaces the horizontal padding and functions more like margin. .g-*, .gx-* and .gy-* classes do not apply here; set --bs-gap instead.
  • As such, unlike .rows, .grids have no negative margins and margin utilities cannot be used to change the grid gutters. Grid gaps are applied horizontally and vertically by default.
  • Inline and custom styles should be viewed as replacements for modifier classes (e.g. style="--bs-columns: 3;" vs class="row-cols-3").
  • Nesting works similarly, but may require you to reset your column counts on each instance of a nested .grid.
The description list example on the typography page uses the flex grid. Either works; CSS grid wins when you need rows and columns, or when items must line up across rows.

Examples

Three columns

Three equal-width columns across all viewports and devices can be created by using the .g-col-4 classes. Add responsive infixes to change the layout by viewport size.

.g-col-4
.g-col-4
.g-col-4
HTML
<div class="grid text-center">
  <div class="g-col-4 border bg-body-tertiary p-3">.g-col-4</div>
  <div class="g-col-4 border bg-body-tertiary p-3">.g-col-4</div>
  <div class="g-col-4 border bg-body-tertiary p-3">.g-col-4</div>
</div>

Responsive

Use responsive classes to adjust your layout across viewports. Here we start with two columns on the narrowest viewports, and then grow to three columns on medium viewports and above.

.g-col-6 .g-col-md-4
.g-col-6 .g-col-md-4
.g-col-6 .g-col-md-4
HTML
<div class="grid text-center">
  <div class="g-col-6 g-col-md-4 border bg-body-tertiary p-3">.g-col-6 .g-col-md-4</div>
  <div class="g-col-6 g-col-md-4 border bg-body-tertiary p-3">.g-col-6 .g-col-md-4</div>
  <div class="g-col-6 g-col-md-4 border bg-body-tertiary p-3">.g-col-6 .g-col-md-4</div>
</div>

Compare that to this two-column layout at all viewports.

.g-col-6
.g-col-6
HTML
<div class="grid text-center">
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
</div>

Wrapping

Grid items automatically wrap to the next line when there is no more room horizontally. Note that the gap applies to horizontal and vertical gaps between grid items.

.g-col-6
.g-col-6
.g-col-6
.g-col-6
HTML
<div class="grid text-center">
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
</div>

Starts

Start classes aim to replace our default grid's offset classes, but they are not entirely the same. CSS Grid creates a grid template through styles that tell browsers to "start at this column" and "end at this column." Those properties are grid-column-start and grid-column-end. Start classes are shorthand for the former. Pair them with the column classes to size and align your columns however you need. Start classes begin at 1 as 0 is an invalid value for these properties.

.g-col-3 .g-start-2
.g-col-4 .g-start-6
HTML
<div class="grid text-center">
  <div class="g-col-3 g-start-2 border bg-body-tertiary p-3">.g-col-3 .g-start-2</div>
  <div class="g-col-4 g-start-6 border bg-body-tertiary p-3">.g-col-4 .g-start-6</div>
</div>

Auto columns

When there are no classes on the grid items (the immediate children of a .grid), each grid item will automatically be sized to one column.

1
1
1
1
1
1
1
1
1
1
1
1
HTML
<div class="grid text-center">
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
</div>

This behaviour can be mixed with grid column classes.

.g-col-6
1
1
1
1
1
1
HTML
<div class="grid text-center">
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
  <div class="border bg-body-tertiary p-3">1</div>
</div>

Nesting

Similar to our default grid system, our CSS Grid allows for easy nesting of .grids. However, unlike the default, this grid inherits changes in the rows, columns and gaps. Consider the example below:

  • We override the default number of columns with a local CSS variable: --bs-columns: 3.
  • In the first auto column, the column count is inherited and each column is one-third of the available width.
  • In the second auto column, we have reset the column count on the nested .grid to 12 (our default).
  • The third auto column has no nested content.

In practice this allows for more complex and custom layouts when compared to the default grid system.

First auto-column
Auto-column
Auto-column
Second auto-column
6 of 12
4 of 12
2 of 12
Third auto-column
HTML
<div class="grid text-center" style="--bs-columns: 3;">
  <div class="border bg-body-tertiary p-3">
    First auto-column
    <div class="grid mt-2">
      <div class="border bg-body-secondary p-2">Auto-column</div>
      <div class="border bg-body-secondary p-2">Auto-column</div>
    </div>
  </div>
  <div class="border bg-body-tertiary p-3">
    Second auto-column
    <div class="grid mt-2" style="--bs-columns: 12;">
      <div class="g-col-6 border bg-body-secondary p-2">6 of 12</div>
      <div class="g-col-4 border bg-body-secondary p-2">4 of 12</div>
      <div class="g-col-2 border bg-body-secondary p-2">2 of 12</div>
    </div>
  </div>
  <div class="border bg-body-tertiary p-3">Third auto-column</div>
</div>

Customizing

Customise the number of columns, the number of rows and the width of the gaps with local CSS variables. This is the main advantage over the flex grid: one inline style, no recompile.

VariableFallback valueDescription
--bs-rows1The number of rows in your grid template
--bs-columns12The number of columns in your grid template
--bs-gap1.5remThe size of the gap between columns (vertical and horizontal)

These CSS variables have no default value; instead, they apply fallback values that are used until a local instance is provided.

No grid classes

Immediate children elements of .grid are grid items, so they are sized without explicitly adding a .g-col class. Set --bs-columns: 3 and you have a three-wide board.

Auto-column
Auto-column
Auto-column
HTML
<div class="grid text-center" style="--bs-columns: 3;">
  <div class="border bg-body-tertiary p-3">Auto-column</div>
  <div class="border bg-body-tertiary p-3">Auto-column</div>
  <div class="border bg-body-tertiary p-3">Auto-column</div>
</div>

Columns and rows

Adjust the number of columns and rows together. A tournament bracket is a natural fit: four rows, three columns, square corners from .frame-bracket on each cell.

Auto-column
Auto-column
Auto-column
Auto-column
Auto-column
Auto-column
Auto-column
Auto-column
Auto-column
Auto-column
Auto-column
Auto-column
HTML
<div class="grid text-center" style="--bs-columns: 3; --bs-rows: 4;">
  <div class="border bg-body-tertiary p-3 frame-bracket">Auto-column</div>
  <div class="border bg-body-tertiary p-3 frame-bracket">Auto-column</div>
  <div class="border bg-body-tertiary p-3 frame-bracket">Auto-column</div>
  <div class="border bg-body-tertiary p-3 frame-bracket">Auto-column</div>
  <div class="border bg-body-tertiary p-3 frame-bracket">Auto-column</div>
  <div class="border bg-body-tertiary p-3 frame-bracket">Auto-column</div>
  <div class="border bg-body-tertiary p-3 frame-bracket">Auto-column</div>
  <div class="border bg-body-tertiary p-3 frame-bracket">Auto-column</div>
  <div class="border bg-body-tertiary p-3 frame-bracket">Auto-column</div>
  <div class="border bg-body-tertiary p-3 frame-bracket">Auto-column</div>
  <div class="border bg-body-tertiary p-3 frame-bracket">Auto-column</div>
  <div class="border bg-body-tertiary p-3 frame-bracket">Auto-column</div>
</div>

Gaps

Change the gap with --bs-gap. Use the token custom properties (--space-0 … --space-8) so the value stays on the scale.

.g-col-6
.g-col-6
.g-col-6
.g-col-6
HTML
<div class="grid text-center" style="--bs-gap: var(--space-2);">
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
</div>

Because gap takes two values, you can set the vertical and horizontal gaps separately: row-gap column-gap.

.g-col-6
.g-col-6
.g-col-6
.g-col-6
HTML
<div class="grid text-center" style="--bs-gap: 0 var(--space-4);">
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
  <div class="g-col-6 border bg-body-tertiary p-3">.g-col-6</div>
</div>

Sass

One limitation of the CSS Grid is that the default classes are still generated by two Sass variables, $grid-columns and $grid-gutter-width. This effectively predetermines the number of classes generated in your compiled CSS. You have two options here:

  • Modify those default Sass variables and recompile your CSS.
  • Use inline or custom styles to augment the provided classes.

The theme sets the switch for you; the rest is at Bootstrap's defaults:

$enable-cssgrid: true;   // scss/_variables.scss
$grid-columns: 12;
$grid-gutter-width: 1.5rem;

For example, you can increase the column count and change the gap size, and then size your grid items with a mix of inline styles and predefined CSS Grid column classes (e.g. .g-col-4).

14 columns
.g-col-4
HTML
<div class="grid text-center" style="--bs-columns: 18; --bs-gap: .5rem;">
  <div class="border bg-body-tertiary p-3" style="grid-column: span 14;">14 columns</div>
  <div class="g-col-4 border bg-body-tertiary p-3">.g-col-4</div>
</div>