Skip to content
Change the site theme
(information)

Grid

A flex-based horizontal grid system used to build layouts.


Guidelines

Guidelines page anchor

The grid component controls the visual layout and spacing between elements on a page or in containers.

About Grid

About Grid page anchor

Grid creates organized and consistent product layouts, by providing a standard for positioning elements. Grid speeds up the designer-to-developer workflow by improving the consistency of design implementations. Use a Grid to layout and align content by applying standard spacing between elements on a page or within a component.

The standard desktop grid has 24-pixel gutters and can support up to 12 columns. The outside gutters are removed from the overall width of the grid.

Grid is built using the Flex component and is responsive. Grid column widths grow and shrink based on the parent element width.

Use Column, which is a child component of Grid, to lay out equal-sized content, such as a feed of cards.

Unequal column widths, using column span

Unequal column widths, using column span page anchor

Use the span prop to allow content to span multiple columns. Span defines how many columns you want the width of your content to take up out of a 12-column grid. The value of span becomes the numerator while 12 is the denominator, which gives us a percentage width value for each column. The default span is 1 column width.

In our example we're setting one column to equal 8 of the 12 columns (span={8}), and the other to be 4 of the 12 columns (span={4}).

Information icon

An important note about span and offset props

When using span or offset, base your layout off a 12-column grid. For example, if you want to have two columns with one spanning twice as much as the other, then one column would span=8 and the other would span=4.

Use offset to push a column to the right by a certain number of columns. For example, a layout with centered columns.

Set equalColumnHeights on a grid container and all columns in a single row will share the height of the tallest column.

This can be useful when trying to visually align Cards where their content is variable.

When columns have equal heights, a single child element will stretch to the height of the column. You may still need to control the width of that child though.

Stacked columns in a vertical layout

Stacked columns in a vertical layout page anchor

Use the vertical prop to stack columns vertically instead of horizontally. The vertical prop can work along with theme breakpoints, so your grid can be vertical on different viewports. For example to have your grid vertical on mobile and not tablet or desktop viewports, use vertical={[true, false, false]}. For a visual example, see the Storybook example(link takes you to an external page) and resize the browser.

A Grid can be nested inside another Grid. For example, you can split a column into multiple smaller columns in order to stack the outer Grid in a responsive view but not the inner Grid.

Grid column span, offset, and gutter props accept responsive values, allowing them to be changed on theme breakpoints. For example, setting span={[6, 8, 2] } on a Column will instruct the column to span 6 columns of the grid at the first breakpoint, 8 columns at the second, and 2 columns at the third breakpoint. Check out the examples below and resize the browser to see the responsive values in action.

When creating responsive layouts with the Grid, it is important to remember to control the vertical prop accordingly. At the breakpoints you wish to stack the columns, set vertical to equal true. This will apply the column gutters vertically, rather than horizontally.

Responsive column offset and span

Responsive column offset and span page anchor

Responsive column gutters

Responsive column gutters page anchor

Grid can be used to compose various types of layouts ranging from whole application pages and views down to individual component layouts.

Information icon

Gutter sizing

For spacing content in a layout wider than 1440 pixels, we recommend using a 24-pixel gutter. Use $space-40 to get a 24-pixel gutter.

For spacing content in a layout narrower than 1440 pixels, we recommend using a 16-pixel gutter. Use $space-30 to get a 16-pixel gutter.

Let's look at a common use case where we need to layout a page with a sidebar and a grid within the page content area.

Grid can also be used for responsive layouts.

Grids can also be used for layouts within other components. For example, we can set up our card content to include 2 columns.

Use Grid whenever you need to layout or align content on a page or within a component. Grid should also be used for responsive page layouts. Since the grid is sized to the full width of its parent container, you may not want to use it for fixed width columns in a variable width container.

4 Column Card

8 Column Card

Do

Base the Column span and offset on a 12-column layout.

Card content

Card content

Card content

Card content

Card content

Card content

Card content

Card content

Card content

Card content

Card content

Card content

Card content

Don't

Don’t use more than 12 columns within Grid.

Card content

Do

Use Grid to align content to the right or left side of a page layout.

Unnecessary HTML elements. Use Box instead.

Don't

Don’t use Grid with only one full-width column of content. This causes unnecessary elements. Box is what you’re looking for here.

Card content

Card content

Card content

Card content

Do

Use Grid to lay out UI elements into consistent columns.

Card content

Card content

Card content

Don't

Don’t let columns grow too small. Gutters should never be wider than columns.


yarn add @twilio-paste/grid - or - yarn add @twilio-paste/core
import {Grid, Column} from '@twilio-paste/core/grid';
const Component = () => (
<Grid>
<Column>Foo</Column>
</Grid>
);
PropTypeDescriptionDefault
equalColumnHeights?booleanSets the height of columns in a row to be equal.
gutter?ResponsiveValue<keyof ThemeShape['space']>Sets the spacing on both sides of a Column. Use a spacing token that represents half of the total space you need between 2 Columns.
vertical?boolean, ResponsiveValue<boolean>Stacks the Columns
PropTypeDescriptionDefault
span?number, ResponsiveValue<number>Sets the width of Columns (how many columns a column can span)
offset?number, ResponsiveValue<number>Sets the left margin of a Column (how many columns a column is offset)

Black lives matter.