Grids

Grids#

Introduction#

Grids are based on a 12 column system, which can adapt to the size of the viewing screen.

A grid directive can be set with the number of default columns (1 to 12); either a single number for all screen sizes, or four numbers for extra-small (<576px), small (768px), medium (992px) and large screens (>1200px), then child grid-item directives should be set for each item.

Note, a single number fixes the number of columns for all screen sizes, whereas four numbers allow the layout to adapt responsively to the screen size, as in the example below.

Try re-sizing the screen to see the number of columns change:

A

B

C

D

Syntax
::::{grid} 1 2 3 4
:outline:

:::{grid-item}
A
:::
:::{grid-item}
B
:::
:::{grid-item}
C
:::
:::{grid-item}
D
:::
::::

.. grid:: 1 2 3 4
    :outline:

    .. grid-item::

        A

    .. grid-item::

        B

    .. grid-item::

        C

    .. grid-item::

        D

You can also use the auto value for the column width(s), to size columns based on the natural width of their content.

short text content

some longer text content

short text content

Multiple rows#

There is no need to add a directive per row; when the number of items exceeds the number of columns, the additional items simply wrap onto new rows, as required:

A

B

C

D

However, to deliberately separate items into distinct rows, use a separate grid directive for each row:

A

B

C

D

Placing a card in a grid#

The grid-item-card directive is a short-hand for placing a card content container inside a grid item (see Cards). Most of the card directive’s options can be used also here:

Title 1

A

Title 2

B

Syntax
::::{grid} 2
:::{grid-item-card}  Title 1
A
:::
:::{grid-item-card}  Title 2
B
:::
::::

.. grid:: 2

    .. grid-item-card::  Title 1

        A

    .. grid-item-card::  Title 2

        B

Controlling spacing between items#

You can set the spacing between grid items with the gutter option. Like for grid columns, you can either provide a single number or four for small, medium and large and extra-large screens.

A

B

A

B

Syntax
::::{grid} 2
:gutter: 1

:::{grid-item-card}
A
:::
:::{grid-item-card}
B
:::
::::

::::{grid} 2
:gutter: 3 3 4 5

:::{grid-item-card}
A
:::
:::{grid-item-card}
B
:::
::::

.. grid:: 2
    :gutter: 1

    .. grid-item-card::

        A

    .. grid-item-card::

        B

.. grid:: 2
    :gutter: 3 3 4 5

    .. grid-item-card::

        A

    .. grid-item-card::

        B

Item level column width#

You can override the number of columns a single item takes up by using the columns option of the grid-item directive. Given the total columns are 12, this means 12 would indicate a single item takes up the entire grid row, or 6 half. Alternatively, use auto to automatically decide how many columns to use based on the item content. Like for grid columns, you can either provide a single number or four for small, medium and large and extra-large screens, and likewise, a single number fixes the item’s width for all screen sizes, overriding any responsive behaviour set by the parent grid.

A

B

C

Syntax
::::{grid} 2
:::{grid-item-card}
:columns: auto

A
:::
:::{grid-item-card}
:columns: 12 6 6 6

B
:::
:::{grid-item-card}
:columns: 12

C
:::
::::

.. grid:: 2

    .. grid-item-card::
        :columns: auto

        A

    .. grid-item-card::
        :columns: 12 6 6 6

        B

    .. grid-item-card::
        :columns: 12

        C

Reversing the item order#

Use the grid directive’s reverse option to reverse the order of the items. This can be useful if you want an item to be on the right side on large screens, but at the top on small screens.

_images/ebp-logo.png

Some text

Nesting grids#

Grids can be nested in other grids to create complex, adaptive layouts:

Item 1.1

Multi-line

content

Item 1.2

Content

Item 2.1

Content

Item 2.2

Content

Item 2.3

Content

Syntax
::::::{grid} 1 1 2 2
:gutter: 1

:::::{grid-item}

::::{grid} 1 1 1 1
:gutter: 1

:::{grid-item-card} Item 1.1

Multi-line

content

:::

:::{grid-item-card} Item 1.2

Content

:::

::::

:::::

:::::{grid-item}

::::{grid} 1 1 1 1
:gutter: 1

:::{grid-item-card} Item 2.1

Content

:::

:::{grid-item-card} Item 2.2

Content

:::

:::{grid-item-card} Item 2.3

Content

:::

::::

:::::

::::::

.. grid:: 1 1 2 2
    :gutter: 1

    .. grid-item::

        .. grid:: 1 1 1 1
            :gutter: 1

            .. grid-item-card:: Item 1.1

                Multi-line

                content

            .. grid-item-card:: Item 1.2

                Content

    .. grid-item::

        .. grid:: 1 1 1 1
            :gutter: 1

            .. grid-item-card:: Item 2.1

                Content

            .. grid-item-card:: Item 2.2

                Content

            .. grid-item-card:: Item 2.3

                Content

See the Bootstrap Grid system for further details.

grid options#

gutter

Spacing between items. One or four integers (for “xs sm md lg”) between 0 and 5.

margin

Outer margin of grid. One (all) or four (top bottom left right) values from: 0, 1, 2, 3, 4, 5, auto.

padding

Inner padding of grid. One (all) or four (top bottom left right) values from: 0, 1, 2, 3, 4, 5.

outline

Create a border around the grid.

reverse

Reverse the order of the grid items.

class-container

Additional CSS classes for the grid container element.

class-row

Additional CSS classes for the grid row element.

grid-item options#

columns

The number of columns (out of 12) a grid-item will take up. One or four integers (for “xs sm md lg”) between 1 and 12 (or auto to adapt to the content).

margin

Outer margin of grid item. One (all) or four (top bottom left right) values from: 0, 1, 2, 3, 4, 5, auto.

padding

Inner padding of grid item. One (all) or four (top bottom left right) values from: 0, 1, 2, 3, 4, 5.

child-direction

Direction of children in the grid item: column (default) or row.

child-align

Alignment of children, along the child-direction: start (default), end, center, justify or spaced.

outline

Create a border around the grid item.

class

Additional CSS classes for the grid item element.

grid-item-card options#

columns

The number of columns (out of 12) a grid-item will take up. One or four integers (for “xs sm md lg”) between 1 and 12 (or auto to adapt to the content).

margin

Outer margin of grid item. One (all) or four (top bottom left right) values from: 0, 1, 2, 3, 4, 5, auto.

padding

Inner padding of grid item. One (all) or four (top bottom left right) values from: 0, 1, 2, 3, 4, 5.

class-item

Additional CSS classes for the grid item element.

Plus all options from card options.