<iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5HGSQD2L" height="0" width="0" style="display:none;visibility:hidden" title="GTM"></iframe>

Grid

An invisible framework responsible for the order and rhythm of our pages. By imposing constraints on layout, the grid makes it easy to achieve consistent and proportionate designs from page-to-page, and across devices.
styleKeys: grid

Use Grid...

  • To promote visual consistency from page to page.
  • To achieve design flexibility.
  • To arrange elements within the Bounded Content.

Don't use Grid...

  • Around full width elements (navigation, footer, Promo Bar, Banner).
  • Within Carousel (not supported).
  • To lay out form fields. Use Form instead.

Structure

SWAN’s Grid organizes content into Rows, each comprising up to 12 Columns, separated by a standard Gutter. The Grid consists of three subcomponents:

  • GridContainer: this is the root element of the Grid. All its children should be Rows.
  • Row: represents a single row within the GridContainer. Each Row should exclusively contain Columns.
  • Column: serves as a column within a Row. It can hold any type of content, including a Nested Grid for more complex layouts.

Grid Container

Divider

Use dividers to add vertical lines between each Column.

The preview has been updated.

Tight gutter

Use gutter="tight" to narrow the gutter between Columns. Only use with Standard Tiles, with skin="product".

The preview has been updated.

Row

Overflow

A Row will display only 12 columns' worth of content per row, but it can contain more than 12. Any extra content will wrap down onto the next line.

Sticky

Use sticky to make a Column remain on screen during scrolling, as long as another element in the same row is also visible.

Important: use the sticky property on both Row and Column to achieve this behavior.

Column

Span

In the React API, use span={*} (0~12) to specify how many grid column a Column spans. In addition, use spanX={*} to override the column span at a given screen size, where * is the number of columns.

  • span: sets the default size for the Column
  • spanXs: overrides the default size on XS screens (default: 12)
  • spanSm: overrides the default size on SM screens
  • spanMd: overrides the default size on MD screens
  • spanLg: overrides the default size on LG screens
  • spanXl: overrides the default size on XL screens

In the Vanilla API, use the swan-col-* (0~12) to specify how many grid column a column spans. In addition, use swan-col-X-* to override the column span at a given screen size, where X is the screen size and * is the number of columns.

  • swan-col-xs-*: overrides the default size on XS screens (default: 12)
  • swan-col-sm-*: overrides the default size on SM screens
  • swan-col-lg-*: overrides the default size on MD screens
  • swan-col-lg-*: overrides the default size on LG screens
  • swan-col-xl-*: overrides the default size on XL screens

The preview has been updated.

Use a single Row to safely contain content exceeding 12 columns. The Row will display the first 12 columns, then automatically wrap any additional content onto the next line.

The preview has been updated.

Offset

In the React API, use offset={*} (0~12) to create an indentation or widen the gap between grid elements. This property shifts a block to the right by a specified number of column widths. In addition, use offsetX={*} to create an offset for a certain screen size, where X is the screen size and * the number of column offset.

  • offset is ignored on XS screens.
  • offsetSm: creates an offset on SM screens.
  • offsetMd: creates an offset on MD screens.
  • offsetLg: creates an offset on LG screens.
  • offsetXl: creates an offset on XL screens.

In the Vanilla API, use the swan-col-offset-* (0~12) class together with the swan-col-* class. In addition, use the swan-col-X-offset-* class to create an offset for a certain screen size, where X is the screen size and * the number of column offset.

  • swan-col-offset is ignored on XS screens.
  • swan-col-sm-offset-*: creates an offset on SM screens.
  • swan-col-md-offset-*: creates an offset on MD screens.
  • swan-col-lg-offset-*: creates an offset on LG screens.
  • swan-col-xl-offset-*: creates an offset on XL screens.

The preview has been updated.

Push / Pull

In the React API, use push={*} (rightward shift) and pull={*} (leftward shift) to reorder Columns in a Row, to change page layout on different screen sizes. In addition, use pushX={*} and pullX={*} to reorder them across different screen sizes, where X is the screen size and * the number of column by which the element is pushed or pulled.

  • push and pull are ignored on XS screens.
  • pushSm and pullSm: change the column order on SM screens.
  • pushMd and pullMd: change the column order on MD screens.
  • pushLg and pullLg: change the column order on LG screens.
  • pushXl and pullXl: change the column order on XL screens.

In the Vanilla API, use swan-col-push-* (rightward shift) and swan-col-pull-* (leftward shift) to reorder Columns in a Row. In addition, use swan-col-X-push-* and swan-col-X-pull-* to reorder them across different screen sizes, where X is the screen size and * the number of column by which the element is pushed or pulled.

  • swan-col-push-* and swan-col-pull-* is ignored on XS screens.
  • swan-col-sm-push-* and swan-col-sm-pull-*: change the column order on SM screens.
  • swan-col-md-push-* and swan-col-md-pull-*: change the column order on MD screens.
  • swan-col-lg-push-* and swan-col-lg-pull-*: change the column order on LG screens.
  • swan-col-xl-push-* and swan-col-xl-pull-*: change the column order on XL screens.

The preview has been updated.

Sticky

Use sticky to make a Column remain on screen during scrolling, as long as another element in the same row is also visible. Be aware that enabling stickiness alters the default behavior of the row: it won't vertically stretch all its columns to the same height.

Important: use the sticky property on both Row and Column to achieve this behavior.

In the React API, use unsticky="xs" on the Column to override the sticky behavior on Extra-Small screens.

In the Vanilla API, add the class swan-col-unsticky-xs to the swan-col-* class to override the sticky behavior on Extra-Small screens.

The preview has been updated.

Flex column

Use flexColumn to evenly distribute the content of a column vertically in relation to others.

The preview has been updated.

Vertically center content

Use verticallyCenterContent to vertically center the content within one column relative to the others.

The preview has been updated.

Floating Container

Use floatingContainer on a child Column with a specified span value, to create a container that sits at the top left of the parent Column. It allows the parent's content to flow and wrap around it.

In the Vanilla API, use the semantically accurate aside tag instead of a div when the content in the floating container (i.e. supporting image, quote) is secondary to the main content.

The preview has been updated.

Use floatingContainerAlignment="right" in addition to floatingContainer to align it to the right.

The preview has been updated.

Accessibility

Grid as List

In the React API, use as="ul" on the GridContainer and as="li" on the Rows when the grid contents are semantically part of a list.

In the Vanilla API, use ul tag with class="swan-grid-container" and li tag with class="swan-row" instead of div tags.

Share
Share

Nested Grid

Place a GridContainer or a Row within a Column to create more flexible layouts. Both the nested row and its parent are divided into 12 columns; the nested row will have narrower columns. Make sure that every Column is a direct child of a Row, and every Row is a direct child of either a GridContainer or a Column.

The preview has been updated.

Small and Extra-Small screens

By default, the Grid spans full width, forming a vertical stack of 12 columns. This can be overridden by dividing the row into sections of 3, 6, or 9 columns only, allowing for customized layout configurations.

At handoff, ensure to define the layout for each specific breakpoint.

Best practices

Do

Use a wrapper element such as Box inside a Column to add custom styling to its child elements.

Don't

Apply Spacing, margin, padding, widths, or any layout-oriented styling onto grid elements, such as GridContainer, Row, or Column.

Do

Use offset when the layout calls for a more playful and exploratory experience.

Don't

Adjust the widths of columns, margins, and gutters.

Do

Use components as intended for layout.

Don't

Scale or stretch components to fit the grid.

Do

Use bgc or backgroundColor to set the background color of any grid element, such as GridContainer, Row, and/or Column.

Don't

Combine grid elements with other components, by putting a grid CSS class and another component's CSS class on the same HTML element.

Do

Use a single Row element to wrap a repeating series of uniform content, such as a series of tiles. This will provide better responsive design, since each Row creates a line break, and these breaks may be unwanted on certain screen sizes. Using a single Row element will avoid these awkward line breaks in the middle of the series.

Don't

Use a Grid in narrow panels like Modal Dialogs, unless you need to divide your content up into horizontal sections.

Props

GridContainer
This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddescriptiondefault
dividersboolean | nullfalse
Decide whether or not to include dividers between each Column.
false
gutter"standard" | "tight" | nullfalse
Specify the gutter width Available options: 'standard', 'tight'
standard
Row
This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddescriptiondefault
stickyboolean | nullfalse
Decide whether or not to allow sticky Column.
false
Column
This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddescriptiondefault
spanNonNullable<1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12>true
The number of columns that this Column should occupy
null
offset0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
The default number of columns that this column should be shifted to the right
null
stickyboolean | nullfalse
Whether or not the Column's content should be sticky
false
push0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
Change the column order by pushing it to the right by a specified number of columns.
null
spanXs1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
The number of columns that this Column should occupy on extra-small screens
null
spanSm1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
The number of columns that this Column should occupy on small screens
null
spanMd1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
The number of columns that this Column should occupy on medium screens
null
spanLg1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
The number of columns that this Column should occupy on large screens
null
spanXl1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
The number of columns that this Column should occupy on X-large screens
null
offsetSm0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
The number of columns that this column should be shifted to the right on small screens
null
offsetMd0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
The number of columns that this column should be shifted to the right on medium screens
null
offsetLg0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
The number of columns that this column should be shifted to the right on large screens
null
offsetXl0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
The number of columns that this column should be shifted to the right on X-large screens
null
pushSm0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
Change the column order on small screens by pushing it to the right by a specified number of columns.
null
pushMd0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
Change the column order on medium screens by pushing it to the right by a specified number of columns.
null
pushLg0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
Change the column order on large screens by pushing it to the right by a specified number of columns.
null
pushXl0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
Change the column order on X-large screens by pushing it to the right by a specified number of columns.
null
pull0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
Change the column order by pulling it to the left by a specified number of columns.
null
pullSm0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
Change the column order on small screens by pulling it to the left by a specified number of columns.
null
pullMd0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
Change the column order on medium screens by pulling it to the left by a specified number of columns.
null
pullLg0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
Change the column order on large screens by pulling it to the left by a specified number of columns.
null
pullXl0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | nullfalse
Change the column order on X-large screens by pulling it to the left by a specified number of columns.
null
flexColumnboolean | nullfalse
In a lineWrap GridContainer, decide whether to arrange the Column's children as a single column, evenly spaced between the top and bottom.
false
verticallyCenterContentboolean | nullfalse
Whether or not the Column's content should be vertically centered within the Row
false
unsticky"none" | "xs" | nullfalse
If a Column is normally sticky, which screen sizes the Column should NOT be sticky on Available options: "none", "xs"
none
floatingContainerboolean | nullfalse
Whether the Column is a Floating Container
false
floatingContainerAlignment"left" | "right" | nullfalse
Alignment for floating Container
left

Related

Was this page useful?

Thanks for your feedback!

Feel free to include your name if you wish to have a follow up conversation.


Published: Aug 11, 2022Last updated: Sep 18, 2024