CSS Grid

Overview

The .grid class sets display: grid with a twelve-column template driven by CSS custom properties. Column spans use .g-col-{n} (which sets grid-column: auto / span n) and placement uses .g-start-{n} (which sets grid-column-start). Both class families have breakpoint-prefixed variants across all six breakpoints.

Both layout systems are active by default — $enable-grid-classes: true and $enable-cssgrid: true. Either can be disabled before compiling by setting its flag to false. See Grid system for the flexbox alternative.

Compared to flexbox

The .grid system differs from .row / .col-* in a few important ways:

• No negative margins. .grid uses the CSS gap property instead of padding-and-negative-margin gutters, so there is no row-edge bleed and .overflow-hidden wrappers are not required.
• Gap applies to both axes. The gap on .grid is horizontal and vertical simultaneously. Use row-gap or column-gap as inline styles to control axes independently.
• Flex utilities have no effect. align-items, justify-content, and similar flex properties do not apply to CSS Grid items.
• CSS custom properties instead of modifier classes. Column count and gap width are runtime-configurable via --cx-grid-columns and --cx-grid-gap; use inline styles where modifier classes would be used on .row.
• Nested grids inherit parent configuration. A nested .grid inherits --cx-grid-columns from the outer grid; override it explicitly when a different column count is needed. See Nesting.

Basic usage

Three equal-width columns in a 12-column grid each span 4 tracks (3 × 4 = 12). Add breakpoint-prefixed classes to change the layout at specific viewport widths — see Responsive classes.

<div class="grid text-center">
  <div class="g-col-4">.g-col-4</div>
  <div class="g-col-4">.g-col-4</div>
  <div class="g-col-4">.g-col-4</div>
</div>

Responsive classes

Breakpoint-prefixed column classes control span width at specific viewport widths. The example below uses two .g-col-6 columns at all viewports, then narrows to three .medium:g-col-4 columns at the medium breakpoint and above:

<div class="grid text-center">
  <div class="g-col-6 medium:g-col-4">.g-col-6 .medium:g-col-4</div>
  <div class="g-col-6 medium:g-col-4">.g-col-6 .medium:g-col-4</div>
  <div class="g-col-6 medium:g-col-4">.g-col-6 .medium:g-col-4</div>
</div>

A two-column layout with no breakpoint variation:

<div class="grid text-center">
  <div class="g-col-6">.g-col-6</div>
  <div class="g-col-6">.g-col-6</div>
</div>

Column wrapping

Grid items wrap to the next row when the total span in the current row exceeds the column count. The gap applies to both horizontal and vertical spacing between items:

<div class="grid text-center">
  <div class="g-col-6">.g-col-6</div>
  <div class="g-col-6">.g-col-6</div>

  <div class="g-col-6">.g-col-6</div>
  <div class="g-col-6">.g-col-6</div>
</div>

Start classes

.g-start-{n} sets grid-column-start to place an item at a specific column track. Classes are generated from .g-start-1 through .g-start-11 — starting at column 12 is not useful in a 12-column grid and is omitted. Pair with .g-col-* to control both position and span:

<div class="grid text-center">
  <div class="g-col-3 g-start-2">.g-col-3 .g-start-2</div>
  <div class="g-col-4 g-start-6">.g-col-4 .g-start-6</div>
</div>

Auto columns

When no .g-col-* class is on a grid item, CSS Grid places it automatically into the next available slot at one column wide (in a 12-column grid, twelve items fill one row):

<div class="grid text-center">
  <div>1</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
</div>

Explicit .g-col-* items and auto-sized items can coexist in the same .grid:

<div class="grid text-center">
  <div class="g-col-6">.g-col-6</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
  <div>1</div>
</div>

Set --cx-grid-columns to a smaller value to produce an auto-column layout with fewer, wider tracks:

<div class="grid text-center" style="--cx-grid-columns: 3;">
  <div>Auto-column</div>
  <div>Auto-column</div>
  <div>Auto-column</div>
</div>

Nesting

A .grid inside another grid item inherits the outer --cx-grid-columns value. Override --cx-grid-columns on the nested .grid to use a different column count. The first inner grid below inherits the parent's 3-column layout; the second resets to 12:

<div class="grid text-center overflow-x-auto" style="--cx-grid-columns: 3;">
  <div>
    First auto-column
    <div class="grid">
      <div>Auto-column</div>
      <div>Auto-column</div>
    </div>
  </div>
  <div>
    Second auto-column
    <div class="grid" style="--cx-grid-columns: 12;">
      <div class="g-col-6">6 of 12</div>
      <div class="g-col-4">4 of 12</div>
      <div class="g-col-2">2 of 12</div>
    </div>
  </div>
  <div>Third auto-column</div>
</div>

Customizing

The three custom properties below can be set on any .grid element — inline or in a stylesheet — to override the default configuration for that instance:

These properties have no default value in CSS; the fallback value kicks in when no instance has been set in the inheritance chain. For example, .grid reads var(--cx-grid-columns, 12) — it uses 12 until --cx-grid-columns is set on a parent or on the .grid element itself.

Columns and gaps

Override column count and gap together with inline styles:

<div class="grid text-center" style="--cx-grid-columns: 4; --cx-grid-gap: 5rem;">
  <div class="g-col-2">.g-col-2</div>
  <div class="g-col-2">.g-col-2</div>
</div>

<div class="grid text-center" style="--cx-grid-columns: 10; --cx-grid-gap: 1rem;">
  <div class="g-col-6">.g-col-6</div>
  <div class="g-col-4">.g-col-4</div>
</div>

Adding rows

.grid generates a single-row template by default. Increase --cx-grid-rows to define a taller explicit grid, then use the grid-row property inline to assign items to specific rows:

<div class="grid text-center" style="--cx-grid-rows: 3; --cx-grid-columns: 3;">
  <div>Auto-column</div>
  <div class="g-start-2" style="grid-row: 2">Auto-column</div>
  <div class="g-start-3" style="grid-row: 3">Auto-column</div>
</div>

Gaps

Set row-gap inline to override the vertical gap independently of --cx-grid-gap:

<div class="grid text-center" style="row-gap: 0;">
  <div class="g-col-6">.g-col-6</div>
  <div class="g-col-6">.g-col-6</div>

  <div class="g-col-6">.g-col-6</div>
  <div class="g-col-6">.g-col-6</div>
</div>

--cx-grid-gap accepts a two-value pair (row-gap column-gap) for asymmetric spacing:

<div class="grid text-center" style="--cx-grid-gap: .25rem 1rem;">
  <div class="g-col-6">.g-col-6</div>
  <div class="g-col-6">.g-col-6</div>

  <div class="g-col-6">.g-col-6</div>
  <div class="g-col-6">.g-col-6</div>
</div>

Auto-fill layout

.grid-fill creates a grid where columns expand equally to fill the available horizontal space, using grid-template-columns: repeat(auto-fit, minmax(0, 1fr)). Unlike .grid, the column count is not configurable — it equals the number of direct children. The gap defaults to 1.5rem and is controlled via --cx-gap (not --cx-grid-gap):

<div class="grid-fill text-center">
  <div>Column</div>
  <div>Column</div>
  <div>Column</div>
  <div>Column</div>
</div>

Subgrid

.grid-cols-subgrid sets grid-template-columns: subgrid on an element, causing it to inherit the parent grid's column track definitions instead of creating its own. Apply it to a multi-column child alongside .grid to align the child's contents to the outer grid's tracks:

<div class="grid text-center">
  <div class="g-col-8 grid grid-cols-subgrid">
    <div class="g-col-4">Subgrid .g-col-4</div>
    <div class="g-col-4">Subgrid .g-col-4</div>
  </div>
  <div class="g-col-4">.g-col-4</div>
</div>

CSS

The CSS Grid system can be customized through Sass variables at compile time.

Sass variables

.g-col-* and .g-start-* classes are generated at compile time from $grid-columns. Increasing $grid-columns extends the generated range; setting --cx-grid-columns at runtime to a value beyond the compiled range requires a style="grid-column: span {n}" inline override for spans without a generated class.

$grid-columns:            12;
$grid-gutter-x:           $space-xlarge;
$grid-gutter-y:           0;
$grid-row-columns:        6;