Flexbox Grid System

Utilities for creating flexbox grids.

How it works

xstyled's grid system uses two properties row and col, and of course all system properties. It’s built with flexbox and is fully responsive. Below is an example and an in-depth look at how the grid comes together.

New to or unfamiliar with flexbox? Read this CSS Tricks flexbox guide for background, terminology, guidelines, and code snippets.

<x.div mx={2}>
  <x.div row mx={-2}>
    <x.div col px={2}>
      col
    </x.div>
    <x.div col px={2}>
      col
    </x.div>
    <x.div col px={2}>
      col
    </x.div>
  </x.div>
</x.div>

The above example creates three equal-width columns on small, medium, large, and extra large devices using our predefined grid classes.

Breaking it down, here’s how it works:

• Rows are wrappers for columns. Each column has horizontal padding (px) for controlling the space between them. This padding is then counteracted on the rows with negative margins (mx). This way, all the content in your columns is visually aligned down the left side.
• In a grid layout, content must be placed within columns and only columns may be immediate children of rows.
• Thanks to flexbox, grid columns without a specified width will automatically layout as equal width columns. For example, four instances of col will each automatically be 25% wide from the small breakpoint and up. See the auto-layout columns section for more examples.
• Column classes indicate the percentage by the col on the current row. So, if you want three equal-width columns across, you can use col={1/4}. Using fraction is often easier to understand.
• Column widths are set in percentages, so they’re always fluid and sized relative to their parent element.
• Columns don't have padding by default, but you can add it with px on col and negative mx on row.
• To make the grid responsive, there are five grid breakpoints, one for each responsive breakpoint: all breakpoints (extra small), small, medium, large, and extra large.
• Grid breakpoints are based on minimum width media queries, meaning they apply to that one breakpoint and all those above it (e.g., col={{ sm: 1/4 }} applies to small, medium, large, and extra large devices, but not the first xs breakpoint).

Be aware of the limitations and bugs around flexbox, like the inability to use some HTML elements as flex containers.

Set your columns width

• A col's value is comprised between 0 and 1 (true means flex: 1).
• It is better to use fractions like 1/2 or 1/4 to quickly see the number of elements displayed on a row.
• If a col value isn't specified, the latter will adjust its size depending on the situation:
  • If the sum of all columns on the same line isn't equal to 1: it will fill up the available space on the line.
  • If the sum of all columns on the same line is equal to 1: it will fill up an entire line below.
• Each col is fully responsive and will adjust its size according to the viewport.

In the following example, the middle column will take 50% of the available space.

<x.div row>
  <x.div col>col</x.div>
  <x.div col={1 / 2}>{`col={1 / 2}`}</x.div>
  <x.div col>col</x.div>
</x.div>

Auto-layout columns

Equal-width

For example, here are two grid layouts that apply to every device and viewport, from xs to xl. Add any number of unit-less props for each breakpoint you need and every column will be the same width.

<x.div row>
  <x.div col>1 of 2</x.div>
  <x.div col>2 of 2</x.div>
</x.div>
<x.div row>
  <x.div col>1 of 3</x.div>
  <x.div col>2 of 3</x.div>
  <x.div col>3 of 3</x.div>
</x.div>

Equal-width multi row

Create equal-width columns that span multiple rows by inserting a <x.div w={1} /> where you want the columns to break to a new line.

<x.div row>
  <x.div col>col</x.div>
  <x.div col>col</x.div>
  <x.div w={1} />
  <x.div col>col</x.div>
  <x.div col>col</x.div>
</x.div>

Setting one column width

Auto-layout for flexbox grid columns also means you can set the width of one column and have the sibling columns automatically resize around it.

<x.div row>
  <x.div col>1 of 3</x.div>
  <x.div col={1 / 2}>2 of 3 (wider)</x.div>
  <x.div col>3 of 3</x.div>
</x.div>
<x.div row>
  <x.div col>1 of 3</x.div>
  <x.div col={2 / 3}>2 of 3 (wider)</x.div>
  <x.div col>3 of 3</x.div>
</x.div>

Variable width content

Use "auto" to size columns based on the natural width of their content.

<x.div row>
  <x.div col>1 of 3</x.div>
  <x.div col="auto">Variable width content</x.div>
  <x.div col>3 of 3</x.div>
</x.div>

Responsiveness

xstyled's grid includes five tiers of predefined classes for building complex responsive layouts. Customize the size of your columns on extra small, small, medium, large, or extra large devices however you see fit. You can also set your own breakpoints in the theme.

All breakpoints

For grids that are the same from the smallest of devices to the largest, use the object notation. Specify a number value when you need a particularly sized column; otherwise, feel free to put the prop without a value (true).

<x.div row>
  <x.div col>-</x.div>
  <x.div col>-</x.div>
  <x.div col>-</x.div>
  <x.div col>-</x.div>
</x.div>
<x.div row>
  <x.div col={2 / 3}>2 / 3</x.div>
  <x.div col={1 / 3}>1 / 3</x.div>
</x.div>

Stacked to horizontal

Using a single set of sm props, you can create a basic grid system that starts out stacked before becoming horizontal with at the small breakpoint (sm).

<x.div row>
  <x.div col={{ xs: 1, sm: 2 / 3 }}>{`{ xs: 1, sm: 2 / 3 }`}</x.div>
  <x.div col={{ xs: 1, sm: 1 / 3 }}>{`{ xs: 1, sm: 1 / 3 }`}</x.div>
</x.div>
<x.div row>
  <x.div col={{ xs: 1, sm: true }}>{`{ xs: 1, sm: true }`}</x.div>
  <x.div col={{ xs: 1, sm: true }}>{`{ xs: 1, sm: true }`}</x.div>
  <x.div col={{ xs: 1, sm: true }}>{`{ xs: 1, sm: true }`}</x.div>
</x.div>

Mix and match

Don’t want your columns to simply stack in some grid tiers? Use a combination of different props for each tier as needed. See the example below for a better idea of how it all works.

{/* Stack the columns on mobile by making one full-width and the other half-width */}
<x.div row>
  <x.div col={{ xs: 1, md: 2 / 3 }}>{`{ xs: 1, md: 2 / 3 }`}</x.div>
  <x.div col={{ xs: 1 / 2, md: 1 / 3 }}>{`{ xs: 1 / 2, md: 1 / 3 }`}</x.div>
</x.div>
{/* Columns start at 50% wide on mobile and bump up to 33.3% wide on desktop */}
<x.div row>
  <x.div col={{ xs: 1 / 2, md: 1 / 3 }}>{`{ xs: 1 / 2, md: 1 / 3 }`}</x.div>
  <x.div col={{ xs: 1 / 2, md: 1 / 3 }}>{`{ xs: 1 / 2, md: 1 / 3 }`}</x.div>
  <x.div col={{ xs: 1 / 2, md: 1 / 3 }}>{`{ xs: 1 / 2, md: 1 / 3 }`}</x.div>
</x.div>
{/* Columns are always 50% wide, on mobile and desktop */}
<x.div row>
  <x.div col={1 / 2}>{`1 / 2`}</x.div>
  <x.div col={1 / 2}>{`1 / 2`}</x.div>
</x.div>

Gutters

Basics

To add gutters, add a container with a horizontal padding (px), a row with a negative horizontal margin (mx) and cols with a horizontal padding (px).

<x.div row mx={-2}>
  <x.div col px={2} />
  <x.div col px={2} />
</x.div>

Vertical and horizontal

To set vertical and horizontal gutters, use p instead of px and m instead of mx.

<x.div row m={-2}>
  <x.div col={1 / 2} p={2} />
  <x.div col={1 / 2} p={2} />
  <x.div col={1 / 2} p={2} />
  <x.div col={1 / 2} p={2} />
</x.div>

External gutter

To add external gutter, remove negative margin on the container.

<x.div row>
  <x.div col={1 / 2} p={2} />
  <x.div col={1 / 2} p={2} />
  <x.div col={1 / 2} p={2} />
  <x.div col={1 / 2} p={2} />
</x.div>

Responsive gutters

Gutters can be responsively adjusted by breakpoint-specific padding and negative margin utilities. To change the gutters in a given row, pair a negative margin utility on the row and matching padding utilities on the cols. The container parent may need to be adjusted too to avoid unwanted overflow, using again matching padding utility.

Here’s an example of customizing the grid at the large (lg) breakpoint and above. We’ve increased the col padding with px={{ lg: 5 }}, counteracted that with mx={{ lg: -5 }} on the parent row and then adjusted the container wrapper with px={{ lg: 5 }}.

<x.div row mx={{ lg: -2 }}>
  <x.div col py={3} px={{ lg: 2 }}>
    Custom column padding
  </x.div>
  <x.div col py={3} px={{ lg: 2 }}>
    Custom column padding
  </x.div>
</x.div>

Alignment

Use flexbox alignment utilities to vertically and horizontally align columns.

Horizontal alignment

Use justifyContent to set the horizontal alignment.

<x.div row justifyContent="flex-start">
  <x.div col={1 / 3} />
  <x.div col={1 / 3} />
</x.div>
<x.div row justifyContent="center">
  <x.div col={1 / 3} />
  <x.div col={1 / 3} />
</x.div>
<x.div row justifyContent="flex-end">
  <x.div col={1 / 3} />
  <x.div col={1 / 3} />
</x.div>
<x.div row justifyContent="space-around">
  <x.div col={1 / 3} />
  <x.div col={1 / 3} />
</x.div>
<x.div row justifyContent="space-between">
  <x.div col={1 / 3} />
  <x.div col={1 / 3} />
</x.div>

Vertical alignment

Use alignItems to set the vertical alignment.

<x.div row alignItems="flex-start" height={100}>
  <x.div col>One of three columns</x.div>
  <x.div col>One of three columns</x.div>
  <x.div col>One of three columns</x.div>
</x.div>
<x.div row alignItems="center" height={100}>
  <x.div col>One of three columns</x.div>
  <x.div col>One of three columns</x.div>
  <x.div col>One of three columns</x.div>
</x.div>
<x.div row alignItems="flex-end" height={100}>
  <x.div col>One of three columns</x.div>
  <x.div col>One of three columns</x.div>
  <x.div col>One of three columns</x.div>
</x.div>

Column wrapping

If the sum of cols weight that are placed within a single row is superior to 1, each group of extra columns will, as one unit, wrap onto a new line.

<x.div row>
  <x.div col={3 / 4} />
  <x.div col={1 / 3} />
  <x.div col={1 / 2} />
</x.div>

Column breaks

Breaking columns to a new line in flexbox requires a small hack: add an element with width: 100% wherever you want to wrap your columns to a new line. Normally this is accomplished with multiple row, but not every implementation method can account for this.

<x.div row>
  <x.div col={{ xs: 1 / 2, sm: 1 / 4 }} />
  <x.div col={{ xs: 1 / 2, sm: 1 / 4 }} />
  {/* Force next columns to break to new line */}
  <x.div w={1} />
  <x.div col={{ xs: 1 / 2, sm: 1 / 4 }} />
  <x.div col={{ xs: 1 / 2, sm: 1 / 4 }} />
</x.div>

Reordering

Order prop

Use order prop for controlling the visual order of your content. Like all utilities, it supports responsive, you can use order={{ sm: 2 }}.

<x.div row>
  <x.div col>First, but unordered</x.div>
  <x.div col order={2}>
    Second, but last
  </x.div>
  <x.div col order={1}>
    Third, but first
  </x.div>
</x.div>

Offsets

You can move columns by applying margin-left (ml) on them.

<x.div row>
  <x.div col={1 / 3} />
  <x.div col={1 / 3} ml="33.333%" />
</x.div>
<x.div row>
  <x.div col={1 / 4} ml="25%" />
  <x.div col={1 / 4} ml="25%" />
</x.div>
<x.div row>
  <x.div col={1 / 2} ml="25%" />
</x.div>

You can also set margin to auto to force sibling columns away from one another.

<x.div row>
  <x.div col={1 / 3} />
  <x.div col={1 / 3} ml="auto" />
</x.div>
<x.div row>
  <x.div col={1 / 4} ml={{ md: 'auto' }} />
  <x.div col={1 / 4} ml={{ md: 'auto' }} />
</x.div>
<x.div row>
  <x.div col="auto" mr="auto" />
  <x.div col="auto" />
</x.div>

Nesting

To nest a grid, specify a col as a row.

<x.div row>
  <x.div col={3 / 4} row>
    {/* {`Level 1: col={3 / 4}`} */}
    <x.div col={2 / 3}>{`col={2 / 3}`}</x.div>
    <x.div col={1 / 3}>{`col={1 / 3}`}</x.div>
  </x.div>
</x.div>