---json
{
    "aliases": [
        { "path": ":docs:layout:component:grid" }
    ],
    "name": "Grid Layout",
    "page_id": "u7kl0ydtjgkaj9vy847wr",
    "title": "Grid Layout: How to create a responsive space distribution on the horizontal axis"
}
---


====== Grid Layout: Responsive distribution of the horizontal space ======


===== 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 [[:docs:styling:breakpoint|screen size]]


<note>
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.
</note>



===== Example =====


==== How to split the space non-evenly with percentage ? ====

You can distribute the available space by giving a [[:docs:styling:dimension|width]] percentage on the children.

This example splits the space in 3 children with:
  * ''50%'' for the first child
  * ''25%'' for the two others.

<webcode>
<code dw>
<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>
</code>
  * Output:
</webcode>

\\
\\
<note>
The default  [[:docs:styling:breakpoint|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.
</note>

==== How to split the available space with a ratio? ====

You can even define the space distribution by giving a ratio on the [[:docs:styling:dimension|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%)

<webcode>
<code dw>
<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>
</code>
  * Output:
</webcode>



\\
\\

<note>
The default  [[:docs:styling:breakpoint|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.
</note>

==== 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 [[:docs:styling:align|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''
<webcode name="Default" frameborder="0">
<code dw>
<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>
</code>
</webcode>



===== Syntax =====
<code dw>
<grid max-line="numberValue" align="x-center-children" gutter="y-5">
   <component width="ratioValue" ></component>
   <component width="ratioValue" ></component>
   ....
</grid>
</code>
where:
  * ''max-line'' (optional) define the maximum number of children by line. The [[:docs:styling:breakpoint|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 [[:docs:styling:breakpoint|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 [[:docs:styling:align|align attribute]] and centers by default the children. (ie ''x-center-children'')
  * ''gutter'' is the gaps between the children. The accepted values are a [[:docs:styling:scale|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 [[:docs:styling:spacing|spacing]]: ''mb-3''


<note>
You can use all [[docs:styling:styling|styling attributes]].
</note>

===== Support =====

==== Why a grid background is not centered ? ====

The gutter feature uses the [[:docs:styling:spacing|padding]] and not margin. 

Because the padding is painted by the background while the margin is not, the dimension of the [[:docs:styling:background|background]] are not uniform in a grid.

If you want a background with you content grid centered, you should:
  * wrap your grid in a [[docs:layout:component:box|box]] with a [[:docs:styling:spacing|padding]] (''p-5'' in the below example) 
  * delete the default top and bottom margin on the grid (ie ''mt-0'' and ''mb-0'')

<webcode>
<code dw>
<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>
</code>
  * Output:
</webcode>