Grid

Grid in Storybook

Wraps the native behavior of CSS Grid as a component. Grid divides a page into major regions and can be used to build advanced layouts.

Children do not need to be GridItems but the GridItem has props for controlling alignment and width within the Grid. For more information on how to use the Grid, check the corresponding CSS properties for the following props:

Prop	CSS grid property
`columns`	`grid-template-columns`
`repeat`	one of `auto-fill`, `auto-fit`, or an integer used in the first argument of the `repeat()` CSS function
`rows`	`grid-template-rows`
`autoRows`	`grid-auto-rows`
`valignContent`	`align-content`
`justifyContent`	`justify-content`
`valignItems`	`align-items`

Columns

Simple example for Grid using gap and columns.

<Grid
  columns={['1fr', '1fr', '1fr']}
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

The columns property is an array of length values of numbers or strings of any css unit, those values define the space each column will occupy, e.g., 1, 1fr, 10%, 20px, ...etc, the items of the columns prop can be a mixture of strings and numbers, please note providing an array of number [1, 1] will cast each number to a grid fraction as 1fr, 1fr:

Repeating column definitions

Simple example for Grid using repeat and columns.

<Grid
  columns={['1fr', '70px']}
  repeat={3}
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

The repeat prop defines a way to repeat column definitions. Providing an integer n will repeat the lengths in columns n times. The other possible values are auto-fill or auto-fit.

auto-fill

<Grid
  columns={['minmax(80px, 1fr)']}
  repeat="auto-fill"
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

auto-fit

<Grid
  columns={['minmax(80px, 1fr)']}
  repeat="auto-fit"
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

Instead of using an integer to define how many times to repeat the columns, the Grid can use auto-fill or auto-fit to automatically define the number of repetitions using the size of the Grid. As the width of the Grid changes, the number of repetitions will adjust to the available space.

The difference between the two is how they handle columns if there is content to add. In the above example, the columns have a minimum width of 50 pixels and max width of 1 fraction of the space. When the space is large enough for another column to exist, auto-fill will place an empty column, whereas auto-fit will collapse any columns that do not have content, allowing the columns to instead use their max-width in this example.

<Grid columns={['minmax(50px, 1fr)']} repeat={'auto-fill'} gap="large">
    ...
</Grid>
<Grid columns={['minmax(50px, 1fr)']} repeat={'auto-fit'} gap="large">
    ...
</Grid>

NOTE: If you want to use the minmax() function, you have to specify it as a string, like in the example above.

Rows

Simple example for Grid using gap and rows.

<Grid
  rows={['1fr', '1fr', '1fr']}
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

Similar to columns, the rows property is an array of length values that define the space each row will occupy. This forms the rows for the explicit grid.

import { Grid } from `@jutro/layout`;

const GridComponent = () => {
    <Grid rows={['1fr', '1fr', '1fr']} gap="large">
        <SomeElement />
        <SomeElement />
        <SomeElement />
    </Grid>
}

AutoRows

Example for Grid using autoRows.

<Grid
  rows={['1fr']}
  autoRows={['`100px`', '2fr']}
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

Any rows that are defined outside of an explicit grid will use the implicit grid. The autoRows prop is an array of length values that will be used by rows not defined using rows. If only one length value is given, any row outside of the explicit grid will take that length.

import { Grid } from `@jutro/layout`;

const GridComponent = () => {
    <Grid rows={['1fr']} autoRows={['`100px`', '2fr']} gap="large">
        <SomeElement />
        <SomeElement />
        <SomeElement />
    </Grid>
}

JustifyContent

Example for Grid using justifyContent.

center

<Grid
  columns={['100px']}
  repeat="3"
  justifyContent="center"
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

right

<Grid
  columns={['100px']}
  repeat="3"
  justifyContent="right"
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

around

<Grid
  columns={['100px']}
  repeat="3"
  justifyContent="around"
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

between

<Grid
  columns={['100px']}
  repeat="3"
  justifyContent="between"
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

The justifyContent prop justifies the columns within the Grid, aligning them to the start, center, or end or the Grid, or spacing them evenly, with space around each column, or space between.

Vertically align items

Example for Grid using valignItems.

stretch

<Grid
  columns={['1fr']}
  repeat="3"
  valignItems="stretch"
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

top

<Grid
  columns={['1fr']}
  repeat="3"
  valignItems="top"
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

middle

<Grid
  columns={['1fr']}
  repeat="3"
  valignItems="middle"
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

bottom

<Grid
  columns={['1fr']}
  repeat="3"
  valignItems="bottom"
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

baseline

<Grid
  columns={['1fr']}
  repeat="3"
  valignItems="baseline"
  gap="large">
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

The valignItems prop vertically aligns the contents of a row. By default, the value is stretch which will stretch all grid items to fill the space. Using any other value (top, middle, bottom, baseline) will give the items their true height and align them accordingly.

Customizing Grid Layout with GridItem

warning

GridItem passes a style prop to a wrapped component. The component then has to pass it to the underlying HTML tag. If it doesn't do that (some Jutro components don't), try passing clone={false} to GridItem:

<GridItem
  colSpan={2}
  clone={false}>
  <SomeElement />
</GridItem>

Then SomeElement will be wrapped in an extra <div> that is styled instead.

colSpan

Simple example for GridItems using colSpan.

<Grid
  columns={['1fr', '1fr', '1fr']}
  rows={['1fr', '1fr']}
  gap="large">
  <GridItem colSpan="3">
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem colSpan="2">
    <SomeElement />
  </GridItem>
</Grid>

The colSpan prop on a GridItem sets how many columns the item will span, can be a string or number.

import { Grid, GridItem } from `@jutro/layout`;

const GridComponent = () => {
    <Grid columns={['1fr', '1fr', '1fr']} rows={['1fr', '1fr']} gap="large">
        <GridItem colSpan="3">1</GridItem>
        <GridItem>2</GridItem>
        <GridItem colSpan="2">3</GridItem>
    </Grid>
}

rowSpan

Simple example for GridItems using rowSpan.

<Grid
  columns={['1fr', '1fr']}
  rows={['1fr', '1fr']}
  gap="large">
  <GridItem rowSpan="2">
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
</Grid>

The rowSpan prop on a GridItem sets how many rows the item will span, can be a string or number.

import { Grid, GridItem } from `@jutro/layout`;

const GridComponent = () => {
    <Grid columns={['1fr', '1fr']} rows={['1fr', '1fr']} gap="large">
        <GridItem rowSpan="2">1</GridItem>
        <GridItem>2</GridItem>
        <GridItem>3</GridItem>
    </Grid>
}

colStart and `rowStart`

Putting the span props together with colStart and rowStart.

<Grid
  columns={['1fr', '1fr', '1fr']}
  rows={['1fr', '1fr', '1fr']}
  gap="large">
  <GridItem colSpan="2">
    <SomeElement />
  </GridItem>
  <GridItem
    rowSpan="2"
    colStart="1">
    <SomeElement />
  </GridItem>
  <GridItem>
    <SomeElement />
  </GridItem>
  <GridItem
    rowSpan="2"
    rowStart="1"
    colStart="3">
    <SomeElement />
  </GridItem>
  <GridItem colSpan="2">
    <SomeElement />
  </GridItem>
</Grid>

The colStart and rowStart props on a GridItem set which column and row the item starts in, respectively. In combination with colSpan and rowSpan these props can be used for a high granularity of customization of Grid layout.

import { Grid, GridItem } from `@jutro/layout`;

const GridComponent = () => {
    <Grid
        columns={['1fr', '1fr', '1fr']}
        rows={['1fr', '1fr', '1fr']}
        gap="large"
    >
        <GridItem colSpan={2}>1</GridItem>
        <GridItem rowSpan={2} colStart={1}>2</GridItem>
        <GridItem>3</GridItem>
        <GridItem rowSpan={2} rowStart={1} colStart={3}>4</GridItem>
        <GridItem colSpan={2}>5</GridItem>
    </Grid>
}

Devices

You can use the phone and tablet properties to override metadata values and apply these overrides to specific devices, such as phones or tablets. This example shows how you can specify different values using the tablet property:

"componentProps": {
    ...
    "tablet": {
        "header": "Value (Tablet)"
    }
    ...
}

Was this page helpful?

Columns​

Repeating column definitions​

auto-fill​

auto-fit​

Rows​

AutoRows​

JustifyContent​

center​

right​

around​

between​

Vertically align items​

stretch​

top​

middle​

bottom​

baseline​

Customizing Grid Layout with GridItem​

colSpan​

rowSpan​

colStart and rowStart​

Devices​