Skip to content

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:

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.

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

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

👉 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.

Gaps

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

Alignment

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

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>.

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.

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.

👉 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 and that aren't filtered out by transferProps helper 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

Prop Type Default Description
alignContent union
  • string
  • shape
    • xs: string
    • sm: string
    • md: string
    • lg: string
    • xl: string
    • x2l: string
    • x3l: string
 
undefined

Content alignment. Accepts any valid value of align-content CSS property. See MDN for more.
alignItems union
  • string
  • shape
    • xs: string
    • sm: string
    • md: string
    • lg: string
    • xl: string
    • x2l: string
    • x3l: string
 
undefined

Items alignment. Accepts any valid value of align-items CSS property. See MDN for more.
autoFlow union
  • string
  • shape
    • xs: string
    • sm: string
    • md: string
    • lg: string
    • xl: string
    • x2l: string
    • x3l: string
 
undefined

Grid auto-flow algorithm to be used. Accepts any valid value of grid-auto-flow CSS property. See MDN for more.
children node 
null

Items to be aligned in the grid. If none are provided nothing is rendered.
columnGap union
  • enum
    • 0
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
  • shape
    • xs: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
    • sm: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
    • md: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
    • lg: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
    • xl: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
    • x2l: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
    • x3l: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
 
4

Gap between columns. Accepts any of spacing values as number. See MDN for more about column-gap.
columns union
  • string
  • shape
    • xs: string
    • sm: string
    • md: string
    • lg: string
    • xl: string
    • x2l: string
    • x3l: string
 
'1fr'

Grid columns. Accepts any valid value of grid-template-columns CSS property. See MDN for more.
justifyContent union
  • string
  • shape
    • xs: string
    • sm: string
    • md: string
    • lg: string
    • xl: string
    • x2l: string
    • x3l: string
 
undefined

Content justification. Accepts any valid value of justify-content CSS property. See MDN for more.
justifyItems union
  • string
  • shape
    • xs: string
    • sm: string
    • md: string
    • lg: string
    • xl: string
    • x2l: string
    • x3l: string
 
undefined

Items justification. Accepts any valid value of justify-items CSS property. See MDN for more.
rowGap union
  • enum
    • 0
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
  • shape
    • xs: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
    • sm: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
    • md: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
    • lg: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
    • xl: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
    • x2l: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
    • x3l: enum
      • 0
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
 
4

Gap between rows. Accepts any of spacing values as number. See MDN for more about row-gap.
rows union
  • string
  • shape
    • xs: string
    • sm: string
    • md: string
    • lg: string
    • xl: string
    • x2l: string
    • x3l: string
 
'auto'

Grid rows. Accepts any valid value of grid-template-rows CSS property. See MDN for more.
tag string 
'div'

HTML tag to render. Can be any valid HTML tag of your choice, usually a block-level element.

GridSpan API

Wrapper for content that should span multiple rows or columns.

Prop Type Default Description
children node 
null

Items to be aligned in the grid. If none are provided nothing is rendered.
columns union
  • number
  • shape
    • xs: number
    • sm: number
    • md: number
    • lg: number
    • xl: number
    • x2l: number
    • x3l: number
 
1

Number of columns to span.
rows union
  • number
  • shape
    • xs: number
    • sm: number
    • md: number
    • lg: number
    • xl: number
    • x2l: number
    • x3l: number
 
1

Number of rows to span.
tag string 
'div'

HTML tag to render. Can be any valid HTML tag of your choice, usually a block-level element.