Grid Layout: How to create a responsive space distribution on the horizontal axis

About

grid is a component that permits to distribute the horizontal space in a responsive fashion (ie suitable for mobile screen).

The children:

will go to a new line in a centered position (by default) if the previous sibling takes more than 100% space (creating a grid)
width may be defined for different screen size

Grid does not mean table. The children are not laid out at the intersection of rows and columns but in a linear fashion from left to right.

Example

How to split the space non-evenly with percentage ?

You can distribute the available space by giving a width percentage on the children.

This example splits the space in 3 children with:

50% for the first child
25% for the two others.

<grid>
    <box width="50%">
        <box width="250" align="center">
            <icon name="bs:inboxes-fill" width="3rem"/>
            == A 250 width box in 50% of the available line space ==
            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud. 
         </box>
    </box>
    <box width="25%">
        <icon name="bs:inboxes-fill" width="3rem"/>
        == 25% box ==
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, 
    </box>
    <box width="25%">
        <icon name="bs:inboxes-fill" width="3rem"/>
        == 25% box ==
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, 
    </box>
</grid>

Output:

A 250 width box in 50% of the available line space

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud.

25% box

Lorem ipsum dolor sit amet, consectetur adipiscing elit,

25% box

Lorem ipsum dolor sit amet, consectetur adipiscing elit,

The default breakpoint is the small breakpoint

A width value of 25% is then equivalent to 100%-xs 25%-sm. It means than on mobile screen (xs breakpoint) each box takes the whole available line space and are therefore stacked.

How to split the available space with a ratio?

You can even define the space distribution by giving a ratio on the width

This example splits the space into 3 via 3 children that have respectively the following space available:

1:4 (25%)
1:2 (50%)
1:4 (25%)

<grid>
    <box width="1:4">
            <icon name="bs:inboxes-fill" width="3rem"/>
            == 1/4 line space ==
            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 
    </box>
    <box width="1:2" align="center-children">
        <box width="300px">
            <icon name="bs:inboxes-fill" width="3rem"/>
            == A 300px box in a half line space ==
            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 
         </box>
    </box>
    <box width="1:4">
            <icon name="bs:inboxes-fill" width="3rem"/>
            == 1/4 line space ==
            Lorem ipsum dolor sit amet, consectetur adipiscing elit, 
    </box>
</grid>

Output:

1/4 line space

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor

A 300px box in a half line space

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

1/4 line space

Lorem ipsum dolor sit amet, consectetur adipiscing elit,

The default breakpoint is the small breakpoint

A width value of 1:3 is then equivalent to 1-xs 1:3-sm. It means that on mobile screen (xs breakpoint) each cell takes the whole available line space and is therefore stacked.

How to center the content vertically?

The grid component is well-suited for vertical and horizontal alignment.

By default, the content is stacked to the top but if you want it to be vertically centered, you can use the children values of the align attribute.

Example:

The grid takes the height of the image
The text is located at the center thanks to y-center-children

<grid align="y-center-children">
  <box align="text-end">
     <heading d3>Headline</heading>
     <text lead>Lead</text>
  </box>
  <box>{{:docs:block:stock_image_surfer_in_the_see.png?400|}}</box>
</grid>

Headline

Lead

Syntax

<grid max-line="numberValue" align="x-center-children" gutter="y-5">
   <component width="ratioValue" ></component>
   <component width="ratioValue" ></component>
   ....
</grid>

where:

max-line (optional) define the maximum number of children by line. The values by breakpoint are 1-xs 2-sm 3-md 4-lg up to the number of children. A value without breakpoint got the sm breakpoint.
width (optional) is a rationale conditional value that defines the space that a cell takes on the horizontal axis. ie:
- a percentage: %: a number between 0 to 100 with the percentage symbol. The total may go over 100. In this case, cells with a cumulative percentage above 100% goes to a new line.
- or a number or ratio from 0 to 1. A cell with 1:3 will take one third of the available line space.
align is the align attribute and centers by default the children. (ie x-center-children)
gutter is the gaps between the children. The accepted values are a scale number (from 1 to 5) with the axis. ie
- x-1 to x-5 for the horizontal gutter
- y-1 to y-5 for the vertical gutter

The default values are:

for gutter: y-5
for spacing: mb-3

You can use all styling attributes.

Support

Why a grid background is not centered ?

The gutter feature uses the padding and not margin.

Because the padding is painted by the background while the margin is not, the dimension of the background are not uniform in a grid.

If you want a background with you content grid centered, you should:

wrap your grid in a box with a padding (p-5 in the below example)
delete the default top and bottom margin on the grid (ie mt-0 and mb-0)

<box spacing="p-5">
  <background opacity="0.3">{{:docs:block:stock_image_surfer_in_the_see.png|}}</background>
  <grid spacing="mt-0 mb-0">
     <box spacing="mt-0">
         <icon name="bs:inboxes-fill" width="3rem"/>
         == 1/2 line space ==
         Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 
     </box>
     <box spacing="mt-0">
         <icon name="bs:inboxes-fill" width="3rem"/>
         == 1/2 line space ==
         Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 
     </box>
  </grid>
</box>

Output:

1/2 line space

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor

1/2 line space

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor