Components

Grid

Grid component is used together with GridItem to lay out other components in a columnar, and optionally responsive, manner.

Examples #

Import Syntax #

import Grid, { GridItem } from 'mineral-ui/Grid';

Note

Layout components, like Grid, have no visual style. They are rendered with background colors and borders in the examples below for illustrative purposes.

Basic Usage #

Use Grid and GridItem to lay out components in a columnar fashion.

A
B
C
<Grid>
  <GridItem>A</GridItem>
  <GridItem>B</GridItem>
  <GridItem>C</GridItem>
</Grid>

Gutters #

Grid will add a default horizontal gap between items. Use the gutterWidth prop to define a different value, including 0 to disable gutters altogether.

Numbers will be appended with px. String values will be passed directly.

A
B
C
A
B
C
A
B
C
A
B
C
A
B
C
() => {
  const propValues = [
    'md', // default
    'xl',
    '2.5em',
    50,
    0
  ];

  const renderGrids = () =>
    propValues.map((value, index) => (
      <Grid gutterWidth={value} key={index}>
        <GridItem>A</GridItem>
        <GridItem>B</GridItem>
        <GridItem>C</GridItem>
      </Grid>
    ));

  return <DemoLayout>{renderGrids()}</DemoLayout>;
}

Columns #

The number of columns used by Grid can be adjusted. This is used in conjunction with GridItem's span prop.

In the illustration below, the first and third rows contain identical GridItems. But the first row has columns set to 15, while the third uses the default of 12. Therefore, the GridItem that spans 7 columns lines up nicely in the first row (15 - 7 = 8, which is neatly divided into two for the remaining "auto" GridItems), but does not in the third (12 - 7 = 5, which does not neatly divide into 2).

Auto
7
Auto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Auto
7
Auto
1
2
3
4
5
6
7
8
9
10
11
12
<DemoLayout>
  <Grid columns={15}>
    <GridItem>Auto</GridItem>
    <GridItem span={7}>7</GridItem>
    <GridItem>Auto</GridItem>
  </Grid>
  <Grid columns={15}>{renderGridItems(15)}</Grid>
  <br />
  <Grid>
    <GridItem>Auto</GridItem>
    <GridItem span={7}>7</GridItem>
    <GridItem>Auto</GridItem>
  </Grid>
  <Grid>{renderGridItems(12)}</Grid>
</DemoLayout>

Align Items #

The alignItems prop defines the alignment of items along the vertical axis.

A
B
C
A
B
C
A
B
C
A
B
C
() => {
  const propValues = [
    'stretch', // default
    'start',
    'center',
    'end'
  ];

  const renderGrids = () => (
    propValues.map((value, index) => (
      <Grid alignItems={value} key={index}>
        <GridItem>A</GridItem>
        <GridItem>B</GridItem>
        <GridItem>C</GridItem>
      </Grid>
    ))
  );

  return (
    <DemoLayout>
      { renderGrids() }
    </DemoLayout>
  )
}

Box Props #

Because Grid composes the Box component, it accepts any of Box's props.

A
B
C
<div>
  {/* You can apply Box props directly to Grid: */}
  <Grid as="section" padding="lg" width={1/2}>
    <GridItem>A</GridItem>
    <GridItem>B</GridItem>
    <GridItem>C</GridItem>
  </Grid>

  {/* Don't wrap Grid in a Box to apply spacing/sizing props:
    <Box padding="lg" width={1/2}>
      <Grid>
        <GridItem>A</GridItem>
        <GridItem>B</GridItem>
        <GridItem>C</GridItem>
      </Grid>
    </Box>
  */}
</div>

Bidirectionality #

Grid reverses its alignment when the direction theme variable is set to rtl (right-to-left).

ا
ب
د
<div dir="rtl">
  <ThemeProvider theme={{ direction: 'rtl' }}>
    <Grid>
      <GridItem>ا</GridItem>
      <GridItem>ب</GridItem>
      <GridItem>د</GridItem>
    </Grid>
  </ThemeProvider>
</div>

API & Theme #

Grid Props #

The Grid component takes the following React props.

NameTypeDefaultDescription
alignItems'stretch'

Align grid items vertically [Responsive-capable]

breakpointsArray<number | string>

Media query (min-width) breakpoints along which to apply props marked "[Responsive-capable]"

childrenReact$Node

Must be GridItem(s)

columnsnumber12

Number of columns (see GridItem's span)

gutterWidth'md'

Size of horizontal gap between grid items

Note

In addition to the props above, Grid also accepts all props for Box.

Undocumented properties will be applied to the root element.

Usage #

When/How to Use #

Grid, together with GridItem, provides an easy way to align components to a columnar layout. With configurable gutters, alignment options, and optionally responsive properties, it is powerful and flexible enough to be the foundation of your app's layout.

Grid is a simpler version of Flex, with the ability to set the number of columns used when calculating item widths. If you need more flexibility for your layout, or you do not need to align to a columnar layout, use Flex instead.

Best Practices #

Use Grid and GridItem to align components to a columnar layout.

Don't use Grid if the content being laid out should not respond to language direction.

Sidebar
Main Content