Grid

A responsive, mobile first, fluid system that appropriately scales 12 columns as the device or viewport size increases

# Overview

# Column Layout

Use rows and columns to lay out content by specifying equal widths for all columns.

# 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

# 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

# xxs

# None

# Vertical

Defines direction for items in a container for all columns of a row. This applies to all columns. Default is horizontal.

# Default

# Vertical

# Wrap/Nowrap

Wrapping columns is the default; however, it is possible to disable or enable column wrapping of a row with the ability to set values based on breakpoint. The disable value also invokes overflow scrolling. This applies to all columns.

# Wrap (Default)

# Nowrap (Scroll)

# Span

Controls column width by overriding columns value for a specific column or columns. Span will override values from columns.

# 12 Columns

# Span 2

# Span 4

# Offset

Adds empty space (or columns) to left or right of a column, either to the left (offset-left) or right (offset-right). This can be applied to an individual column.

# Offset Left

# Offset Right

# Align Self

Overrides row-level alignment for a column. This can be applied to an individual column.

# Nested Grids

Defines nested columns (also known as isRow).

# Simple

# Complex

# 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
  • Use list markup for content layout. List markup allow contents to be structured which makes it easier for assistive technologies

This component has compliance with following WCAG guidelines:

  • WCAG SC 1.3.2: Meaningful Sequence: Cedar Design System does not provide for Flexbox’s order property. Reverse order or reordering of items is not allowed. Content must be presented in a correct reading sequence to comply with accessibility standards

# 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
  • Maximum width of 1232px:
    • Allows for padding between grid and browser window
    • Utilities are available to manage layout and presentation
    • Stay within max width to match the width of the global navigation
XS (Extra Small) < 768px 16px 16px
SM (Small) ≥ 768px 16px 16px
MD (Medium) ≥ 992px 32px 32px
LG (Large) ≥ 1232px 32px 32px

  • Limit to 12 columns per row:
    • If more than 12 columns are placed within a single row, each group of extra columns will, as one unit, wrap onto a new line
    • If a layout does not need 12 columns, specify that number to the engineering team

  • Gutters separate columns with pre-defined padding:
XS (Extra Small) < 768px 16px gutters (8px on left + 8px on right)
SM (Small) ≥ 768px 16px gutters (8px on left + 8px on right)
MD (Medium) ≥ 992px 32px gutters (16px on left +16px on right)
LG (Large) ≥ 1232px 32px gutters (16px on left +16px on right)

# 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 rules 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

Grids are built from two components: CdrRow and CdrCol.

# Props

# CdrRow

cols

name

string

type

N/A

default

Number of equal-width columns in the row; however the value of ‘auto’ will size columns as wide as the column’s content. Possible values: { ‘1’ through ‘12’ | ‘auto’ }. Also accepts responsive values @breakpoint: ‘2 4@md’.

justify

name

string

type

N/A

default

Justify columns within a row. See CSS Flexbox justify-content. Possible values: { ‘left’ | ‘center’ | ‘right’ | ‘around’ | ‘between’ }. Also accepts responsive values @breakpoint: ‘center right@lg’.

align

name

string

type

N/A

default

Align columns of different heights. See CSS Flexbox align-items. Possible values: { ‘top’ | ‘middle’ | ‘bottom’ | ‘stretch’ }. Also accepts responsive values @breakpoint: ‘top middle@sm’.

gutter

name

string

type

N/A

default

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

vertical

name

string

type

N/A

default

Changes row to a column layout. See CSS Flexbox flex-direction. Possible values: { ‘vertical’ }. Also accepts responsive values @breakpoint: vertical@md’.

wrap

name

string

type

N/A

default

Enables row wrapping. Change only if overriding `nowrap`. See CSS Flexbox flex-wrap.

nowrap

name

string

type

N/A

default

Disables row wrapping and enables overflow scrolling. See CSS Flexbox flex-wrap. Possible values: { ‘nowrap’ }. Also accepts responsive values with @breakpoint: ‘nowrap@md’.

type

name

string

type

"normal"

default

Sets grid to use <ul> and <li> or <div>. Possible values: { ‘normal’ | ‘list’ }

# CdrCol

span

name

string

type

N/A

default

Number of columns (out of 12) the column will span. Functions like bootstrap col-* classes. Overrides widths set by ‘cols’ prop on CdrRow. Possible values: { ‘1’ through ‘12’ }. Also accepts responsive values with @breakpoint: ‘12 8@lg’.

offsetLeft

name

string

type

N/A

default

Adds up to 12 columns of empty space to left of an individual column. Possible values: { ‘1’ through ‘12’ }. Also accepts responsive values with @breakpoint: ‘12 8@lg’.

offsetRight

name

string

type

N/A

default

Adds up to 12 columns of empty space to right of an individual column. Possible values: { ‘1’ through ‘12’ }. Also accepts responsive values with @breakpoint: ‘12 8@lg’.

alignSelf

name

string

type

N/A

default

Aligns individual column by overriding CdrRow alignment. See CSS Flexbox align-self. Possible values: { ‘top’ | ‘middle’ | ‘bottom’ | ‘stretch’ }. Also accepts responsive values with @breakpoint: ‘middle@sm’.

isRow

name

boolean

type

false

default

Makes the column act as a CdrRow. Setting this value to true will expose all props of CdrRow in addition to CdrCol props.

# Slots

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

# CdrRow

default

name

Sets the innerHTML for CdrRow content. This includes text and html markup.

# CdrCol

default

name

Sets the innerHTML for CdrCol content. This includes text and html markup.

# Usage

CdrRow functions as a flexbox container, and CdrCol functions as a flexbox item.

  • Always use CdrRow and CdrCol together:
    • Attempting to use either without the other will not work
    • Never include other elements as immediate children of CdrRow, other than CdrCol
  • The grid system is mobile-first, flexbox based, and 12 columns wide. Many props mirror the flexbox API and work as you’d expect a CSS flexbox to work.

New to or unfamiliar with flexbox? Read this CSS Tricks flexbox guide for background, terminology, guidelines, and examples.

# CdrCol Content Width

Immediate children of cdr-col are flexed due to a flex height display bug in some versions of Safari. This causes immediate children to be full-width and display stacked horizontally. Wrapping child elements in a single <div> element will fix these problems (if undesired).



 


 



<cdr-row>
  <cdr-col>
    <div>
      <p>This will display</p>
      <p>As expected</p>
    </div>
  </cdr-col>
</cdr-row>
1
2
3
4
5
6
7
8

# Nested Grids

Nested grids are made by nesting cdr-col and adding the is-row prop to the cdr-col that acts as the row wrapper:

  • Add is-row prop to cdr-col that has other cdr-col as children
  • is-row will expose all props for both column and row

 




<cdr-row cols=”3”>
  <cdr-col is-row span=”6” cols”2”>
    <cdr-col></cdr-col>
  </cdr-col>
</cdr-row>
1
2
3
4
5

# Utility class use

Any custom or utility classes should not be added to either cdr-row or cdr-col as they can have adverse effects on things like gutters which can break the layout. Custom or utility classes should only be added to your own markup/content.



 





<cdr-row>
  <cdr-col>
    <div class="my-class cdr-space-inset-one-x">
      ...
    </div>
  </cdr-col>
</cdr-row>
1
2
3
4
5
6
7