(sd-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: ::::{grid} 1 2 3 4 :outline: :::{grid-item} A ::: :::{grid-item} B ::: :::{grid-item} C ::: :::{grid-item} D ::: :::: `````{dropdown-syntax} ````{tab-set-code} ```{literalinclude} ./snippets/myst/grid-basic.txt :language: markdown ``` ```{literalinclude} ./snippets/rst/grid-basic.txt :language: rst ``` ```` ````` You can also use the `auto` value for the column width(s), to size columns based on the natural width of their content. ::::{grid} auto :::{grid-item} :outline: :padding: 2 short text content ::: :::{grid-item} :outline: :padding: 2 some longer text content ::: :::{grid-item} :outline: :padding: 2 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: ::::{grid} 3 :outline: :::{grid-item} A ::: :::{grid-item} B ::: :::{grid-item} C ::: :::{grid-item} D ::: :::: However, to deliberately separate items into distinct rows, use a separate `grid` directive for each row: ::::{grid} 3 :outline: :::{grid-item} A ::: :::{grid-item} B ::: :::: ::::{grid} 3 :outline: :::{grid-item} C ::: :::{grid-item} 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](./cards.md)). Most of the `card` directive's options can be used also here: ::::{grid} 2 :::{grid-item-card} Title 1 A ::: :::{grid-item-card} Title 2 B ::: :::: `````{dropdown-syntax} ````{tab-set-code} ```{literalinclude} ./snippets/myst/grid-card.txt :language: markdown ``` ```{literalinclude} ./snippets/rst/grid-card.txt :language: rst ``` ```` ````` ## 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. ::::{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 ::: :::: `````{dropdown-syntax} ````{tab-set-code} ```{literalinclude} ./snippets/myst/grid-gutter.txt :language: markdown ``` ```{literalinclude} ./snippets/rst/grid-gutter.txt :language: rst ``` ```` ````` ## 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`. ::::{grid} 2 :::{grid-item-card} :columns: auto A ::: :::{grid-item-card} :columns: 12 6 6 6 B ::: :::{grid-item-card} :columns: 12 C ::: :::: `````{dropdown-syntax} ````{tab-set-code} ```{literalinclude} ./snippets/myst/grid-card-columns.txt :language: markdown ``` ```{literalinclude} ./snippets/rst/grid-card-columns.txt :language: rst ``` ```` ````` ## 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. ::::{grid} 1 1 2 2 :reverse: :::{grid-item} ```{image} ./images/ebp-logo.png :width: 200px :class: sd-m-auto ``` ::: :::{grid-item-card} Some text ::: :::: ## Nesting grids Grids can be nested in other grids to create complex, adaptive layouts: ::::::{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 ::: :::: ::::: :::::: `````{dropdown-syntax} ````{tab-set-code} ```{literalinclude} ./snippets/myst/grid-nested.txt :language: markdown ``` ```{literalinclude} ./snippets/rst/grid-nested.txt :language: rst ``` ```` ````` See the [Bootstrap Grid system](https://getbootstrap.com/docs/5.0/layout/grid/) 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 [](cards:options).