Grid Patterns

๐Ÿ“˜

Looking for a deeper dive?

You can find more detailed examples at https://gymnastjs.github.io/gymnast

Columns

Building a columns layout with gymnast can be done in multiple ways. For instance:

  • Add a <Col /> container
  • Add as many <Col /> elements as you want
  • Each <Col /> with size="auto" will have an equal width, no matter the number of columns.
  • If a container have no size, it defaults to the entire row (100%)
<Col>
  <Col size="auto">First Column</Col>
  <Col size="auto">Second Column</Col>
  <Col size="auto">Third Column</Col>
  <Col size="auto">Fourth Column</Col>
</Col>

Column Sizes

Define the size of each column individually
If you want to change the size of a single column, you can set size to a number from 1 to the max number of columns (defaults to 12). Not specifying a size defaults to full width (size 12 by default).

<Col>
  <Col size={8}>8</Col>
  <Col size={2}>2</Col>
  <Col size={2}>2</Col>

  <Col size={6}>6</Col>
  <Col size={3}>3</Col>
  <Col size={3}>3</Col>

  <Col size={4}>4</Col>
  <Col size={4}>4</Col>
  <Col size={4}>4</Col>

  <Col size={2}>5</Col>
  <Col size={5}>5</Col>
  <Col size={5}>5</Col>

  <Col>12</Col>
</Col>

Offset

While you can use empty columns (like <Col />) to create horizontal space around other <Col /> elements, you can also use <Offset /> like:

<Col>
  <Offset size={4} />
  <Col size={4}4</Col>
  <Col size={4}4</Col>

  <Col size={4}4</Col>
  <Offset size={4} />
  <Col size={4}4</Col>

  <Col size={4}4</Col>
  <Col size={4}4</Col>
  <Offset size="auto" />
</Col>

Columns responsiveness

By default, behavior is the same across all resolutions. If you want columns to behave differently between different breakpoint, specify the size using breakpoints:

const size = {
  small: 12,
  medium: 8,
  large: 4
}

<Col>
  <Col size={size}>Resize</Col>
</Col>

๐Ÿ“˜

Resize

If you want to see the difference, open the CodeSandbox example and resize your browser and see the columns change size with width changes.

Nesting

You can nest columns to have more flexibility in your design. All <Grid /> and <Col /> elements are infinitely nestable.

<Col>
  <Col size={6}>
    First Column
    <Col size={6}>1st Nested Column</Col>
    <Col size={6}>2nd Nested Column</Col>
  </Col>
  <Col size={6}>
    Second Column
    <Col size={6}>50%</Col>
    <Col size="auto">Auto</Col>
    <Col size="auto">Auto</Col>
  </Col>
</Col>

Columns gap

Each column has a horizontal gap equal to gutter / 2 which defaults to 12px.

Since the gap is on each side of a column, the gap between two adjacent columns is a full gutter or 24px.

Vertically, each column sets a vertical gap of gutter which defaults to 24px.

The specific spacing values can be configured through <ConfigProvider /> so these are just the defaults.

<Col>
  <Col size="auto">First Column</Col>
  <Col size="auto">Second Column</Col>
  <Col size="auto">Third Column</Col>
  <Col size="auto">Fourth Column</Col>
</Col>

Gapless

If you want to remove the space between the columns, set margin to 0. This is the same as using the <Grid /> component instead of <Col />. In fact, <Col /> is implemented as a <Grid /> component with some margin defaults. It looks like this (simplified):

const Col = props => <Grid margin={[0, gutter / 2, gutter]} {...props} />

Four columns without spaces would look like:

<Col>
  <Grid size="auto">First Column</Grid>
  <Grid size="auto">Second Column</Grid>
  <Grid size="auto">Third Column</Grid>
  <Grid size="auto">Fourth Column</Grid>
</Col>

Custom Gaps

Most of the time, <Col /> and <Grid /> will have the default gaps you want to use. Other times you may want to customize your margins and paddings.

gymnast allows setting different spacing values for each direction using a css-like syntax. For instance the following are all equivalent:

<Grid margin="1 0" />
<Grid margin="1, 0" />
<Grid margin={[1, 0]} />
<Grid marginTop={1} marginBottom={1} marginLeft={0} marginRight={0} />

padding follows the same syntax:

<Grid padding={1} />
<Grid padding="1, 0" />

Note that padding cannot be combined with any other padding direction (e.g. padding and paddingBottom is ambiguous because they both set the bottom padding). The same applies to margin.

The numbers used here are multiples of base which defaults to 8px. Thus, margin={2} will set a margin in all directions of 8px * 2 = 16px.

To avoid having to remember specific common values, you can define aliases. For instance, the following are equivalent:

<Grid margin="L" />
<Grid margin="3" />

You can see the full list of aliases here.