grid docs

Grid

A flexible 12-column grid with responsive breakpoint options.

Published Last updated: 5.8.0 Change log Github NPM
Twig Usage
{% include '@bolt-components-grid/grid.twig' with {
  gutter: 'medium',
  row_gutter: 'medium',
  items: [
    {
      column_start: '1',
      column_span: '1',
      row_start: '1',
      row_span: '1',
      valign: 'start',
      content: 'Item Content',
    },
  ]
} only %}
Schema
Note: when assigning component props as HTML attributes on a web component, make sure to use kebab-case.
Grid (grid.twig)
Prop Name Description Type Default Value Option(s)
attributes

A Drupal-style attributes object with extra attributes to append to this component.

object
gutter

Spacing between the columns of the grid.

string medium
  • none, small, medium, large
row_gutter

Spacing between the rows of the grid.

string medium
  • none, small, medium, large
items

Array of grid items to render inside the grid.

array
    • attributes

      A Drupal-style attributes object with extra attributes to append to this component.

    • content

      Content to render inside each grid item.

    • valign

      Vertical alignment of the grid item itself.

      • start, center, end
    • column_start

      The vertical starting point of the grid item. This accepts any number from 1 to 12, and their perspective responsive variations for advanced usage, for example, 6@small means the column start is set at 6 for any browser width larger and equal to the small breakpoint. This prop is required to make the grid work in Internet Explorer.

    • column_span

      The number of columns the grid item should span across. This accepts any number from 1 to 12, and their perspective responsive variations for advanced usage, for example, 6@small means the column span is set at 6 for any browser width larger and equal to the small breakpoint.

    • row_start

      The horizontal starting point of the grid item. This prop is required to make the grid work in Internet Explorer.

    • row_span

      The number of rows the grid item should span across.

Grid Item (grid-item.twig)
Prop Name Description Type Default Value Option(s)
attributes

A Drupal-style attributes object with extra attributes to append to this component.

object
valign

Vertical alignment of the grid item itself

string auto
  • auto, start, center, end
column_start

The general column the grid item should start on. For example, a with the attributes columns="3" start-column="2" would start on the 2nd column and extend for 3 columns so it would span the 2nd, 3rd and 4th column.

string
column_end

The general column the grid item should stop on. For example, a with the attributes start-column="2" end-column="3" would start on the 2nd column and extend until the 3rd column.

string
column_span

The number of columns the should span across

string
row_start

Specifies a grid item’s start position within the grid row

string auto
row_end

Specifies a grid item’s ending position within the grid row

string auto
row_span

Specifies the number of rows a should span across

string auto
Install Install
npm install @bolt/components-grid
Dependencies @bolt/core-v3.x

grid

Bolt Grid is a 12-column grid design approach

By using The Grid to design layouts, consistency is guaranteed. If your goal is to confine your layout to a 12-column grid and have elements spaced and lined up consistently using the Bolt spacing system, The Grid is for you. Otherwise, you should not use The Grid, there is the List component for simple layouts and alignments.

1 2 3 4 5 6 7 8 9 10 11 12

grid start and span

Column start and column span

The Bolt Grid is built on the concept of column start and column span, this allows the user to have full control of the grid layout.

Common usage

Main content in the center (column start 3 and column span 8) with 2 asides.

Aside
Main
Aside

Main content with an aside (column start 9 and column span 4).

Main
Aside

Row start and row span

Row start and row span are also available, they are for less common layouts.

Row
Row
Row
Start at column 2 and row 2 and span 2 rows.
Row
Row
Row

All possible start and span options

Please refer to the Bolt Breakpoints for all possible breakpoint names. number@breakpoint-name means starting at that specific breakpoint, change to the number defined. For example: column_span: "6@small" means starting at the small breakpoint, span 6 columns.

Regular Option Responsive Option
column_start 1 to 12 1@breakpoint-name to 12@breakpoint-name
column_span 1 to 12 1@breakpoint-name to 12@breakpoint-name
row_start 1 to 12 1@breakpoint-name to 12@breakpoint-name
row_span 1 to 12 1@breakpoint-name to 12@breakpoint-name

grid gutter variations

None Gutter

Span 4 columns
Span 4 columns
Span 4 columns

Small Gutter

Span 4 columns
Span 4 columns
Span 4 columns

Medium Gutter

Span 4 columns
Span 4 columns
Span 4 columns

Large Gutter

Span 4 columns
Span 4 columns
Span 4 columns

grid row gutter variations

None Row Gutter

Span 12 columns
Span 12 columns
Span 12 columns

Small Row Gutter

Span 12 columns
Span 12 columns
Span 12 columns

Medium Row Gutter

Span 12 columns
Span 12 columns
Span 12 columns

Large Row Gutter

Span 12 columns
Span 12 columns
Span 12 columns

Each item can span from 1 to 12 columns

Span 3 columns
Span 6 columns
Span 9 columns
Span 12 columns

Use any combination that adds up to 12 columns to form a row

In this example, the item 1 is starting at column 1 and spanning 3 columns wide, the item 2 is starting at column 4 and spanning 9 columns.

Item 1
Item 2

In this example, the item 1 is starting at column 1 and spanning 6 columns wide, the item 2 is starting at column 7 and spanning 6 columns.

Item 1
Item 2

Each item can span from 1 to 12 rows

Row span works as long as you have multiple rows. For example, if you only have 2 rows of content, you cannot have an item to span 3 rows because the highest you can get is 2.

3 rows 6 rows 9 rows 12 rows
Row
Row
Row
Row
Row
Row
Row
Row
Row
Row
Row
Row

Responsive breakpoint options

Use the @breakpoint options to do advanced responsive layouts.

  • Item 1
    1. Up to small breakpoint: start at row 2 and span 12 columns
    2. Starting at small breakpoint: start at row 1 and span for 4 columns
    3. Starting at medium breakpoint: start at row 1 and span for 3 columns
    column_start: '1', column_span: '12 3@small 4@medium', row_start: '2 1@small'
  • Item 2
    1. Up to small breakpoint: start at row 1 and span 12 columns
    2. Starting at small breakpoint: start at row 1 and span for 8 columns
    3. Starting at medium breakpoint: start at row 1 and span for 9 columns
    column_start: '1 5@small 4@medium', column_span: '12 8@small 9@medium', row_start: '1 1@small'
Item 1
Item 2

grid item align variations

Horizontal item alignment

The alignment must be set manually by using column start and column span, that way the user can position the item exactly as intended with the flexibility doing more than the common start, center, and end alignments.

Standard alignments

To align an item to the start, set column start to 1.

Column start at 1 and span 4

To align an item to the center, set column start by using this formula: (12 - column_span) / 2 + 1.

Column start at 5 and span 4

To align an item to the end, set column start by using this formula: (12 - column_span) + 1.

Column start at 9 and span 4

Advanced alignments

Offset by 1 column from the center.

Column start at 4 and span 8

Offset by 1 column from the start.

Column start at 2 and span 2

grid item valign variations

Vertical item alignment

Vertical alignment of an item can simply be defined by the valign prop.

Start

Item
Item
Item

Center

Item
Item
Item

End

Item
Item
Item

Traditional Columns and Rows

  1. Use a parent grid to create rows, each item span for 12 columns.
  2. Inside each item of the parent grid, pass a child grid to create columns.
Item
Item
Item
Item
Item
Item
Item
Item
Item