Grid

A layout container using CSS grid. Supports Spectrum dimensions as values to ensure consistent and adaptive sizing and spacing.

Introduction#

The Grid component can be used to layout its children in two dimensions with CSS grid. Any React Spectrum component can be used as a child, and Spectrum dimension variables can be used to define sizing and spacing, which ensures consistency across applications, and allows the layout to adapt to different devices automatically. In addition, these values can be autocompleted in many IDEs for convenience.

All Grid props also support object syntax to define responsive layouts that change at certain breakpoints. See the layout docs for more details.

Examples#

Explicit grids#

This example shows how to build a common application layout with a header, sidebar, content area, and footer. It uses the areas prop to define the grid areas, along with columns and rows to define the sizes. Each child uses the gridArea prop to declare which area it should be placed in.

<Grid
  areas={[
    'header  header',
    'sidebar content',
    'footer  footer'
  ]}
  columns={['1fr', '3fr']}
  rows={['size-1000', 'auto', 'size-1000']}
  height="size-6000"
  gap="size-100">
  <View backgroundColor="celery-600" gridArea="header" />
  <View backgroundColor="blue-600" gridArea="sidebar" />
  <View backgroundColor="purple-600" gridArea="content" />
  <View backgroundColor="magenta-600" gridArea="footer" />
</Grid>

<Grid
  areas={[
    'header  header',
    'sidebar content',
    'footer  footer'
  ]}
  columns={['1fr', '3fr']}
  rows={['size-1000', 'auto', 'size-1000']}
  height="size-6000"
  gap="size-100">
  <View backgroundColor="celery-600" gridArea="header" />
  <View backgroundColor="blue-600" gridArea="sidebar" />
  <View backgroundColor="purple-600" gridArea="content" />
  <View backgroundColor="magenta-600" gridArea="footer" />
</Grid>

<Grid
  areas={[
    'header  header',
    'sidebar content',
    'footer  footer'
  ]}
  columns={[
    '1fr',
    '3fr'
  ]}
  rows={[
    'size-1000',
    'auto',
    'size-1000'
  ]}
  height="size-6000"
  gap="size-100"
>
  <View
    backgroundColor="celery-600"
    gridArea="header"
  />
  <View
    backgroundColor="blue-600"
    gridArea="sidebar"
  />
  <View
    backgroundColor="purple-600"
    gridArea="content"
  />
  <View
    backgroundColor="magenta-600"
    gridArea="footer"
  />
</Grid>

Implicit grids#

This example creates an implicit grid. It declares the columns using the repeat function to automatically generate as many columns as fit, and uses the autoRows prop to set the size of the implicitly created rows. The items are centered horizontally within the container, and have a gap between them defined using a Spectrum dimension variable. Resize your browser to see how items reflow.

<Grid
  columns={repeat('auto-fit', 'size-800')}
  autoRows="size-800"
  justifyContent="center"
  gap="size-100">
  {colors.map(color =>
    <View key={color} backgroundColor={color} />
  )}
</Grid>

<Grid
  columns={repeat('auto-fit', 'size-800')}
  autoRows="size-800"
  justifyContent="center"
  gap="size-100">
  {colors.map(color =>
    <View key={color} backgroundColor={color} />
  )}
</Grid>

<Grid
  columns={repeat(
    'auto-fit',
    'size-800'
  )}
  autoRows="size-800"
  justifyContent="center"
  gap="size-100"
>
  {colors.map(
    (color) => (
      <View
        key={color}
        backgroundColor={color}
      />
    )
  )}
</Grid>

Props#

Helper functions#

React Spectrum offers JavaScript versions of the CSS functions that are often used with CSS grid. These allow using Spectrum variables to define dimensions, and are typed to allow IDE autocomplete.

repeat#

The repeat function can be used to make a repeating fragment of the columns or rows list.

minmax#

The minmax function defines a size range greater than or equal to min and less than or equal to max.

fitContent#

The fitContent function clamps a given size to an available size.