CSS Grid

Wrapper for working with CSS Grid

# Overview

CdrGrid is a simple wrapper for working with CSS Grid. Any valid CSS Grid properties can be applied to a CdrGrid or it's grid items, allowing for more flexible layouts to be built using less markup and CSS classes.

CdrGrid applies a default responsive gutter which can be customized using the gutter prop or overridden completely using CSS. The examples on this page are meant to illustrate some basic usage of CSS grid but are by no means exhaustive. Note that when constructing page layouts your entire page should be wrapped in a single cdr-container to ensure the proper outer margins are maintained.

New to or unfamiliar with CSS Grid? We recommend these resources for getting up to speed with CSS Grid:

# Column Layout

Use rows and columns to lay out content by specifying equal widths for all columns. Columns have a minimum width, if columns cannot be spaced equally etc. new line

# Justify

Define x-axis alignment and distribute space for all columns per row. Containers may have set widths or may be flexible with max widths defined. This applies to all columns with left as the default value.

# Left

# Center

# Around

# Between

# Align

Define y-axis alignment per row and distribute space across all columns per row. This applies to all columns with stretch as the default value.

# Top

# Bottom

# Middle

# Stretch

# Varied Alignment

# Gutter

Defines gutter size for all columns on a row and maintains gutter size by breakpoint. This applies to all columns. When this value is not set, default sizes are used.

# Default

The default gutter value is medium@xs medium@sm large@md large@lg.

# Small

# None

# Custom Responsive Gutters

# Scrolling Grid

Scrollable grids can be created using the grid-auto-flow property set to column for horizontal scrolling or row for vertical scrolling.

# List Markup

For accessibility reasons it may make sense to construct your grid using list markup.

# Span

Column width can be controlled using the grid-template-columns property.

# Complex Span

Individual items can override their sizing with grid-column and grid-row;

# Offset

Offsets can be created on grid items using the grid-column-start property.

# Nested Grids

Grids can be nested to any depth by passing another CdrGrid in as a grid item.

# Responsive Grids

CSS grid layouts using fr units will be inherently responsive, however additional breakpoint-specific behaviors can be created using media queries.

.responsive-grid-example {
  grid-template-columns: '1fr 1fr 1fr';
  @include cdr-md-mq-down {
    grid-template-columns: '1fr';
  }
}
1
2
3
4
5
6

# Handling Leftover Columns

For grid layouts with an unknown number of items you may end up with an incomplete row at the end. These "leftover" or "orphan" columns can be styled using a combination of the last-child/nth-last-child and nth-child selectors depending on how many items are in your grid row.

/* Target leftover grid columns */

.orphan-grid-example-2x2 div:last-child:nth-child(2n + 1) {
  grid-column: 1 / span 2;
}
1
2
3
4
5

For grid layouts with an odd number of columns per row, make the grid-template and grid-items each twice as large so they can be offset as needed to center them.


/* Make grid columns take up twice as much space */
.orphan-grid-example-3x3 div { grid-column: span 2;}

/* If 2 columns are leftover, center them by moving the second to last element to the right by 1 */
.orphan-grid-example-3x3 div:nth-last-child(2):nth-child(3n + 1) {
  grid-column: 2 / span 2;
}

/* If 1 column is leftover, center it by moving it to the right by 2 */
.orphan-grid-example-3x3 div:last-child:nth-child(3n + 1) {
  grid-column: 3 / span 2;
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# Named Grid Areas

Use grid-template-areas to layout grid items named using the grid-area property.

# Accessibility

To ensure that usage of this component complies with accessibility guidelines:

  • Low-vision users should be able to increase the size of the text by up to 200 percent without breaking the layout
  • Ensure the tab order for grid content makes sense. Avoid re-ordering the placement of items to differ from their order in the markup.
  • Use list markup for content layout. List markup allow contents to be structured which makes it easier for assistive technologies

# Guidelines

# Use When

  • Arranging content and components into rows and columns
  • Laying out a page of 2+ rows of body content (apart from site navigation), some of which may or may not have columns
  • Applying responsive rules to columns of a row and/or regions of a page layout, or a container of many components
  • Arranging elements within a single component with two or more zones, including those aligned to the left or right edge

# Don't Use When

  • Presenting a multi-row columnar data display, such as features or specs of a product. Instead, use Table

# The Basics

Columns, gutters, and margins scales as a fluid system as the device and viewport increases from a small devices to a large device:

grid concept at desktop and mobile sizes grid breakpoints

# Anatomy

gutter margins and grids
XS (Extra Small) < 768px 16px 16px
SM (Small) ≥ 768px 16px 16px
MD (Medium) ≥ 992px 32px 32px
LG (Large) ≥ 1232px 32px 32px

# Content

  • Prioritize your content by organizing content to highlight the most important information
  • Use white space created by grid system because too much dense information can be disorienting and overwhelming

# Behavior

  • Avoid breaking alignment or slightly oversizing a container to stick out for visual interest or to add emphasis
  • Create relationships and hierarchy between content elements by using the margins and gutters in the grid shared by the page layout

# Do/Don't

Image showing proper grid usage
Do maintain a consistent grid system.
Image showing mixed grid usage
Don't mix this grid and other grid systems.
Image showing grid margins
Do maintain global margins.
Image showing overly large side margins
Don't make margins too large.
Image showing grid gutters
Do maintain global gutters.
Image showing overly large grid gutters
Don't make gutters too large.

# Responsiveness

To build an effective responsive grid:

  • Design mobile first:
    • Use the XS (≤ 768px) viewport width applicable to small devices like a phone
    • Start with a one column layout and add columns as needed
  • Apply responsive media queries to the grid and its contained content at relevant breakpoints including SM (≥ 768px) and MD (≥ 998px)
  • Complete and optimize the layout for the widest LG (≥ 1232px) viewport width
  • Inspect responsive displays in between each breakpoint for how content responds across the fluid spectrum

# API

# Props

gutter

name

string

type

N/A

default

Defines gutter size. Default gutter size is 16px for @xs and @sm (medium) and 32px for @md and @lg (large). Possible values: { ‘none’ | ‘small’ | 'medium' | 'large' }. Also accepts responsive values @breakpoint: none@md’.

tag

name

string

type

div

default

Sets the tag type for the CdrGrid element. Accepts any HTML tag name that can function using `display: grid`. Useful for constructing list based layouts.

# Slots

Find more information about using Slots in the article Getting Started as a Developer.

default

name

Slot for CdrGrid content.

# Usage

CdrGrid functions as a grid container, and it's immediate children are grid items.

  • Use any native CSS grid properties on the CdrGrid or it's grid items
  • Use media queries to add responsiveness to your grid layout
  • Wrap your entire page layout in a single cdr-container