Some props/prop values deprecated in SWAN v3.14
Refer to the information on props/prop values provided further down this page. Find more information and migration documentation in the Deprecation roadmap.
Grid
Provides a structured layout framework for page content, ensuring consistent alignment, spacing, and responsiveness across components and screens.
styleKeys: grid
Use Grid...
- Inside Bounded Content to create page layouts.
Don't use Grid...
- Inside Carousel or Modal Dialog, as it's not supported.
- For form fields. Use Form.
Overview
See Page Layout for guidance on using Grid with other layout components.
Structure
Grid is based on an invisible 12-segment structure, where each segment has a fluid width. As the grid resizes, segments scale proportionally.
To structure layouts, Grid consists of three components that must be used in order: GridContainer > Row > Column. Nested layouts can be created by placing a GridContainer inside a Column.
The preview has been updated.
Segment vs Column
- Segments define the layout structure, acting as invisible guides for alignment and spacing.
- Column is a flexible wrapper component that can span multiple segments, holding content and adapting responsively.
Segments create the structure, while the Column component controls how content is placed within that structure.
Spanning and wrapping
Columns can span 1 to 12 Grid Segments. If a Row does not contain enough Grid Segments, Columns will wrap within a row.
Columns without a set span will span 1 Segment. On xs breakpoints, all columns span 12 Segments, unless explicitly overridden with spanXs. Push, pull, and offset has no effect on xs breakpoints.
The preview has been updated.
Grid Container
Use GridContainer to stack Rows vertically. Place the top level Grid Container inside Bounded Content for page layouts.
The preview has been updated.
Nested Grid
GridContainer can be placed inside Column to create a nested Grid. Nested Grids do not contain the same outer padding as top-level Grids, allowing for alignment between the two.
The preview has been updated.
Dividers
Use dividers to add vertical lines between each Column.
The preview has been updated.
Tight Gutter
gutter is deprecated in SWAN v3.14
As it is rarely used, it has been deprecated to improve consistency for customers and reduce UX debt.
Use gutter="tight" only with product skin Standard Tiles to narrow the gutter between Columns.
The preview has been updated.
Row
Use Row to group Columns horizontally inside GridContainer.
Vertical Gap
Grid does not provide any vertical spacing when columns wrap within a row. Use verticalGap to adjust this spacing as needed. verticalGap=”matchGutter” can be used to match the horizontal gutter.
Sticky
Use sticky on Row when a Column inside uses Sticky. Note that this will prevent columns from stretching to the same height.
Column
Use Column inside Row to define flexible, responsive grid sections. Columns have padding inside that will align content to the grid segments.
Span
Use span={*} to extend columns across multiple Grid Segments.
The preview has been updated.
Offset
Use offset={*} to create horizontal spacing between columns. This is useful when adjusting spacing across different breakpoints. See responsive for more details.
The preview has been updated.
Push and Pull
Use push={*} and pull={*} to reorder columns. Push moves columns to the right, while pull moves them to the left. This is useful for arranging content differently in the DOM than it appears visually, or for reordering content at different breakpoints. See responsive for more details.
The preview has been updated.
Sticky
Use sticky on the column and parent row to keep a Column on screen while its Row is visible during scrolling.
The preview has been updated.
Flex Column
Use flexColumn to evenly distribute the column content vertically.
The preview has been updated.
Vertically Center Content
Use verticallyCenterContent to vertically center the content.
The preview has been updated.
Floating Container
Use floatingContainer on a child Column with a span value to position it at the top left of the parent Column, allowing content to flow around it.
The preview has been updated.
Use floatingContainerAlignment="right" in addition to floatingContainer to align it to the right.
The preview has been updated.
Responsive
Use breakpoint-specific overrides to adjust column properties at certain breakpoints. These overrides do not cascade to other breakpoints. Replace X with the appropriate breakpoint, e.g. spanSm.
- Span – Use
spanX={*}for breakpoint-specific overrides. - Offset – Use
offsetX={*}for breakpoint-specific overrides. - Push and Pull – Use
pushX={*}andpullX={*}for breakpoint-specific overrides. - Sticky – Use
unsticky="xs"on the column to override sticky on [xs] breakpoints.
Vanilla
In the Vanilla API:
- Span – use
swan-col-*(0-12). Useswan-col-X-*for breakpoint-specific overrides. - Offset – use
swan-col-offset-*(0-12) withswan-col-*. Useswan-col-X-offset-*for breakpoint-specific overrides. - Push and Pull – use
swan-col-push-*andswan-col-pull-*. Useswan-col-X-push-*andswan-col-X-pull-*for breakpoint-specific overrides. - Sticky – use
swan-col-push-*andswan-col-pull-*. Useswan-col-X-push-*andswan-col-X-pull-*for breakpoint-specific overrides. - Flex Column – use
swan-col-flex-column. - Vertically Center Content – use
swan-col-vertically-center. - Floating Container – use
<aside>instead of<div>when the floating content (e.g., an image or quote) is secondary to the main content.
Accessibility
Grid as a List
In the React API, use as="ul" on GridContainer and as="li" on Rows for list-based content.
In the Vanilla API, use <ul class="swan-grid-container"> and <li class="swan-row"> instead of <div>.
How to use Grid in Figma
The three Grid components, GridContainer, Row and Column do not exist in Figma. While it’s important to understand how they work, when designing in Figma, the key focus is on organising content into Columns that are aligned to the Grid segments.
- Segments define the layout structure, acting as invisible guides for alignment and spacing.
- Column is a flexible wrapper component that can span multiple segments, holding content and adapting responsively.
The SWAN UI Kit provides grid styles that help you design within SWAN’s grid system. These styles overlay your designs with Grid segment guidelines, allowing you to structure layouts effectively. You can then arrange content within Columns (frames), spanning segments as needed.
The UI Kit provides two grid styles:
- Grid & Bounded Content. Apply to pages. This is the starting grid that should be used in most instances.
- Nested Grid. Use inside other grids. Apply this to column frames to represent nested grids.
SWAN’s Grid system is primarily designed to be used at the page level. It is not suitable for suitable for pages with floating menus such as Studio, nor for use inside container components such as Card or Modal Dialog.
For a full overview of SWAN’s Grid and Page Layout, watch Grid and Page Layout: A guide for designers.
Applying grid styles
Select the page frame and apply the Grid & Bounded Content grid style.
Ensure Layout grid guides are visible (ctrl + G)
Understanding grid styles
Bounded Content is represented by a thin pink line on either side of the page.
Grid segments are represented in beige. Align Row and Column frames to these.
On xs breakpoints, all columns span 12 Segments, unless explicitly overridden with spanXs.
In Figma we show 2 segments on xs to make it easier to design with.
Remember to apply the correct breakpoint mode in Figma. See Responsive System for more.
Using grid styles
Columns
When designing with Grid, think in Columns. Columns span a set amount of grid segments. In Figma, columns can be represented by frames.
It can be helpful to name these frames as “Column (span X)”.
Gaps can be left between columns. This is called an offset column in code.
Rows
In code, Columns sit inside Rows that span the full-width of the Grid. This allows you to adjust the layout of the page in different sections. These can also be represented by frames in Figma.
If Autolayout is applied to the Row frame, use space/gutter-between/standard on the horizontal gap to represent the Grid gutters.
Content
Align content placed inside Columns such as text and SWAN components to the Column.
Do not align content to Grid segments.
See Space for more details on laying out content inside Columns.
Nested Grids
Grids can be nested inside other grids to create more complex layouts. To do this in Figma, apply the Nested Grid grid style to a Column frame.
Columns inside the Nested Grid align to its segments. Not to the top-level Grid segments.
Mobile (xs)
By default there is 1 segment on the xs breakpoint (mobile), and 12 on sm and larger. Unless overridden, Columns will stack on xs.
In Figma we show 2 segments on xs to make it easier to design with.
In code, Grid can be overridden to allow for layouts with inline columns.
Support
If you need further support or have feedback on any of these learning materials, reach out the Design System Team.
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.
| prop | type | required | description | default |
|---|---|---|---|---|
| dividers | boolean | null | false | Decide whether or not to include dividers between each Column. | false |
| gutter | "standard" | "tight" | null | false | ⚠️ Deprecated - This is deprecated without a replacement.
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.
| prop | type | required | description | default |
|---|---|---|---|---|
| sticky | boolean | null | false | Decide whether or not to allow sticky Column. | false |
| verticalGap | 0 | 1 | 2 | "0" | "1" | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12" | "matchGutter" | null | false | Adds a vertical gap between wrapping columns.
`matchGutter` can be used to match the standard horizontal gap (note: does not work on 'tight' gutters) built in to grid. | null |
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.
| prop | type | required | description | default |
|---|---|---|---|---|
| span | NonNullable<1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12> | true | The number of columns that this Column should occupy | null |
| offset | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | The default number of columns that this column should be shifted to the right | null |
| sticky | boolean | null | false | Whether or not the Column's content should be sticky | false |
| push | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | Change the column order by pushing it to the right by a specified number of columns. | null |
| spanXs | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | The number of columns that this Column should occupy on extra-small screens | null |
| spanSm | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | The number of columns that this Column should occupy on small screens | null |
| spanMd | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | The number of columns that this Column should occupy on medium screens | null |
| spanLg | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | The number of columns that this Column should occupy on large screens | null |
| spanXl | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | The number of columns that this Column should occupy on X-large screens | null |
| offsetSm | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | The number of columns that this column should be shifted to the right on small screens | null |
| offsetMd | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | The number of columns that this column should be shifted to the right on medium screens | null |
| offsetLg | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | The number of columns that this column should be shifted to the right on large screens | null |
| offsetXl | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | The number of columns that this column should be shifted to the right on X-large screens | null |
| pushSm | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | Change the column order on small screens by pushing it to the right by a specified number of columns. | null |
| pushMd | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | Change the column order on medium screens by pushing it to the right by a specified number of columns. | null |
| pushLg | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | Change the column order on large screens by pushing it to the right by a specified number of columns. | null |
| pushXl | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | Change the column order on X-large screens by pushing it to the right by a specified number of columns. | null |
| pull | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | Change the column order by pulling it to the left by a specified number of columns. | null |
| pullSm | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | Change the column order on small screens by pulling it to the left by a specified number of columns. | null |
| pullMd | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | Change the column order on medium screens by pulling it to the left by a specified number of columns. | null |
| pullLg | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | Change the column order on large screens by pulling it to the left by a specified number of columns. | null |
| pullXl | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | null | false | Change the column order on X-large screens by pulling it to the left by a specified number of columns. | null |
| flexColumn | boolean | null | false | In a lineWrap GridContainer, decide whether to arrange the Column's children as a single column, evenly spaced between the top and bottom. | false |
| verticallyCenterContent | boolean | null | false | Whether or not the Column's content should be vertically centered within the Row | false |
| unsticky | "none" | "xs" | null | false | If a Column is normally sticky, which screen sizes the Column should NOT be sticky on
Available options: "none", "xs" | none |
| floatingContainer | boolean | null | false | Whether the Column is a Floating Container | false |
| floatingContainerAlignment | "left" | "right" | null | false | Alignment for floating Container | left |
How does Grid meet your needs?
Related