CSS grid utilities
Within a page layout, there are many scenarios where a multi-column layout is needed for content. For these scenarios, we offer several CSS utility classes.
The ds-grid class creates a CSS grid with the following defaults:
- 1 column
- 24px gap
- 0px outer padding
Equal column example
To create a layout with equal width columns, use the following modifiers:
- ds-grid--cols-1: 1 column
- ds-grid--cols-2: 2 columns
- ds-grid--cols-3: 3 columns
- ds-grid--cols-4: 4 columns
Example code
<!-- Four equal width columns -->
<div class="ds-grid ds-grid--cols-4">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
<div>Item 4</div>
</div>
<!-- Three equal width columns -->
<div class="ds-grid ds-grid--cols-3">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</div>
<!-- Two equal width columns -->
<div class="ds-grid ds-grid--cols-2">
<div>Item 1</div>
<div>Item 2</div>
</div>
Responsive example (media queries)
In many cases, you may need more flexibility than a fixed number of columns across all breakpoints. Our design system utilises variant modifier prefixes to adjust the number of columns according to the standard set of breakpoints.
Example usage: mq-sm:ds-grid--cols-2
Explanation: Starting from the small breakpoint, set the number of columns to 2.
Variant modifiers and their min-width values:
|
Variant modifier |
Min-width value |
|---|---|
|
mq-sm |
540px |
|
mq-md |
768px |
|
mq-lg |
992px |
|
mq-xl |
1200px |
|
mq-2xl |
1400px |
Example code:
<!--
Initial value: Single column
Medium breakpoint: 4 columns
-->
<div class="ds-grid mq-md:ds-grid--cols-4">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
<div>Item 4</div>
</div>
Responsive example (container queries)
In some cases, rather than adjusting the grid based on the viewport, you might want to adjust it based on the container size. This is especially useful in more complex layouts. We use the same pattern as the media query example, but with the prefix cq- instead of mq-. When using this variation remember to specify a container by adding the class ds-grid-container.
Example usage: cq-sm:ds-grid--cols-2
Explanation: When the container element (ds-grid-container) reaches the small container width, set the number of columns to 2.
Variant modifiers and their min-width values:
|
Variant modifier |
Min-width value |
|---|---|
|
cq-sm |
540px |
|
cq-md |
720px |
|
cq-lg |
980px |
|
cq-xl |
1140px |
|
cq-2xl |
1320px |
Example code:
<!-- Initial value: Single column Medium container width: 4 columns -->
<!-- Note: For container queries, specify a container for the grid with "ds-grid-container" -->
<div class="ds-grid-container">
<div class="ds-grid cq-md:ds-grid--cols-4">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
<div>Item 4</div>
</div>
</div>
Grid gap
Grid gap refers to the space between items on the grid. The default gap is 24px, but there may be cases where you need to adjust the gap size.
Available options:
- ds-grid--gap-0: No gap
- ds-grid--gap-xs: 8px gap
- ds-grid--gap-sm: 16px gap
- ds-grid--gap-md: 24px gap
Example code:
<!-- Four equal width columns - with no gap -->
<div class="ds-grid ds-grid--cols-4 ds-grid--gap-0">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
<div>Item 4</div>
</div>
Grid outer padding
Grids can have outer padding applied outside the column layout.
Available options:
- ds-grid--padding-0: No outer padding (default)
- ds-grid--padding-sm: Small outer padding (12px)
- ds-grid--padding-md: Medium outer padding (24px)
Example code:
<!-- Four equal width columns - with medium outer padding -->
<div class="ds-grid ds-grid--cols-4 ds-grid--padding-md">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
<div>Item 4</div>
</div>
Grid fixed flexible / flexible fixed
For layouts with unequal columns, you can fix one column and allow the other to fill the available space.
Available options:
- ds-grid--fixed-flexible: Fix the first column, allow the second to fill the available space.
- ds-grid--flexible-fixed: Fix the second column, allow the first to fill the available space.
By default, the fixed column takes a grid size of auto. To set the fixed column to a specific proportion, you can use:
- ds-grid--fixed-w-1/3: Set the fixed column to one-third of the width.
- ds-grid--fixed-w-1/4: Set the fixed column to one-quarter of the width.
Example code:
<!-- Fixed flexible -->
<div class="ds-grid ds-grid--fixed-flexible">
<div>Fixed</div>
<div>Flexible</div>
</div>
<!-- Flexible fixed -->
<div class="ds-grid ds-grid--flexible-fixed">
<div>Flexible</div>
<div>Fixed</div>
</div>