Grid

The responsive Grid layout aligns content into an organized grid.

Basic Usage

To implement the Grid component, you need to import it first:

import { Grid } from '@react-ui-org/react-ui';

And use it:

<Grid>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
</Grid>

See API for all available options.

General Guidelines

This component implements the native CSS grid layout, a powerful tool for two-dimensional layouts. You may use any value accepted by grid-template-columns, grid-template-rows, grid-auto-flow, align-content, align-items, justify-content, justify-items, and CSS properties in corresponding API options of the component.
To align your items in the grid, simply wrap them with the Grid component. Unlike other grid frameworks and UI libraries, no additional markup like GridItem or Cell is necessary for your items. But it's there when you really need it—see Advanced Layouts.
For forms, use rather the FormLayout component which is designed specifically for that purpose.
The Grid component is so powerful that it enables you to build even very advanced layouts without having to write a single line of custom CSS. See Advanced Layouts for more.

👉 Vertical margin of items inside Grid is reset to zero.

Columns

Stack is the default outcome of Grid. Use the columns option to organize your items into a grid.

<Grid columns="1fr 1fr 1fr">
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
</Grid>

You can use the repeat() function to specify a recurring pattern.

<Grid columns="repeat(3, 1fr)">
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
</Grid>

Combine repeat() with auto-fit and minmax() to build automatic responsive layouts.

<Grid columns="repeat(auto-fit, minmax(200px, auto))">
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
</Grid>

👉 If you need your items to have equal height even with the content of varying lengths, it may be necessary to set height: 100% on them.

Rows

Use columns and rows to specify a more complicated grid layout.

<Grid columns="1fr 2fr" rows="auto 200px auto">
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
</Grid>

Gaps

Both column and row gaps can be customized. The value must correspond to any of available spacings.

<Grid columns="repeat(3, 1fr)" columnGap={2} rowGap={6}>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
</Grid>

Alignment

Individual items and the entire grid content can be aligned along both axes.

<Grid
  columns="repeat(3, 10em)"
  alignItems="center"
  justifyItems="center"
  justifyContent="center"
>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item<br /> with two lines</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
</Grid>

Custom HTML Tag

To render as a list, for example, just change the output tag to ul or ol and wrap your items with <li>.

<Grid tag="ul">
  <li>
    <docoff-placeholder bordered>List item</docoff-placeholder>
  </li>
  <li>
    <docoff-placeholder bordered>List item</docoff-placeholder>
  </li>
  <li>
    <docoff-placeholder bordered>List item</docoff-placeholder>
  </li>
</Grid>

Media Queries

If you need to build more complicated layouts, you have full control over the grid definition. Just specify your grid layout for breakpoints where a change of layout is needed. The Grid component is written with the mobile-first approach so values for small breakpoints are used until they're overridden by a bigger breakpoint.

👉 With this syntax there are no defaults for individual breakpoints.

📐 Try resizing your browser to see how it works.

<Grid
  columns={{
    xs: '1fr',
    md: '1fr 2fr',
  }}
  columnGap={{
    xs: 4,
    md: 2,
    lg: 4,
  }}
  rows={{
    xs: 'auto auto 200px 200px',
    md: 'auto 200px auto',
  }}
  rowGap={{
    xs: 3,
    md: 4,
  }}
>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
  <docoff-placeholder bordered>Grid item</docoff-placeholder>
</Grid>

Advanced Layouts

Wrap your content with the GridSpan component to span it over multiple columns or rows. Use the autoFlow option to control the layout when combined with responsive columns and rows.

<Grid
  autoFlow={{
    xs: 'row dense',
    sm: 'column',
  }}
  columns={{
    xs: 'repeat(2, 1fr)',
    sm: 'repeat(4, 1fr)',
  }}
  rows={{
    xs: 'repeat(8, 50px)',
    sm: 'auto 100px auto auto',
  }}
>
  <docoff-placeholder bordered>Grid item 1</docoff-placeholder>
  <docoff-placeholder bordered>Grid item 2</docoff-placeholder>
  <docoff-placeholder bordered>Grid item 3</docoff-placeholder>
  <docoff-placeholder bordered>Grid item 4</docoff-placeholder>
  <docoff-placeholder bordered>Grid item 5</docoff-placeholder>
  <GridSpan columns={2} rows={2}>
    <docoff-placeholder bordered height="100%">
      Grid item spanning over two lines and two rows
    </docoff-placeholder>
  </GridSpan>
  <docoff-placeholder bordered>Grid item 6</docoff-placeholder>
  <docoff-placeholder bordered>Grid item 7</docoff-placeholder>
  <docoff-placeholder bordered>Grid item 8</docoff-placeholder>
  <docoff-placeholder bordered>Grid item 9</docoff-placeholder>
  <docoff-placeholder bordered>Grid item 10</docoff-placeholder>
  <docoff-placeholder bordered>Grid item 11</docoff-placeholder>
  <docoff-placeholder bordered>Grid item 12</docoff-placeholder>
</Grid>

👉 autoFlow (used in the example above) implements the grid-auto-flow CSS property. Check MDN to fully understand available options.

Forwarding HTML Attributes

In addition to the options below in the component's API section, you can specify any HTML attribute you like. All attributes that don't interfere with the API of the React component are forwarded to the root HTML element of your choice provided by tag, which is <div> by default. This enables making the component interactive and helps to improve its accessibility.

👉 For the full list of supported attributes refer to:

API

GridSpan API

Wrapper for content that should span multiple rows or columns.