Edit page

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.

πŸ“ Try resizing the playground to see it in action.

πŸ‘‰ 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 React synthetic events or any HTML attribute you like. All attributes that don't interfere with the API are forwarded to the HTML element of your choice provided by tag, which is <div> by default. It enables making the component interactive and helps to improve its accessibility.

πŸ‘‰ Refer to the MDN reference for the full list of supported attributes of the div element or any other element of your choice.

API

Prop nameTypeDefaultRequiredDescription
alignContentstring β”‚ { "xs": "string", "sm": "string", "md": "string", "lg": "string", "xl": "string", "x2l": "string", "x3l": "string" }undefinedfalse

Content alignment. Accepts any valid value of align-content CSS property. See MDN for more.

alignItemsstring β”‚ { "xs": "string", "sm": "string", "md": "string", "lg": "string", "xl": "string", "x2l": "string", "x3l": "string" }undefinedfalse

Items alignment. Accepts any valid value of align-items CSS property. See MDN for more.

autoFlowstring β”‚ { "xs": "string", "sm": "string", "md": "string", "lg": "string", "xl": "string", "x2l": "string", "x3l": "string" }undefinedfalse

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

childrennodenullfalse

Items to be aligned in the grid. If none are provided nothing is rendered.

columnGap0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7 β”‚ { "xs": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7", "sm": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7", "md": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7", "lg": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7", "xl": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7", "x2l": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7", "x3l": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7" }4false

Gap between columns. Accepts any of spacing values as number. See MDN for more about column-gap.

columnsstring β”‚ { "xs": "string", "sm": "string", "md": "string", "lg": "string", "xl": "string", "x2l": "string", "x3l": "string" }'1fr'false

Grid columns. Accepts any valid value of grid-template-columns CSS property. See MDN for more.

justifyContentstring β”‚ { "xs": "string", "sm": "string", "md": "string", "lg": "string", "xl": "string", "x2l": "string", "x3l": "string" }undefinedfalse

Content justification. Accepts any valid value of justify-content CSS property. See MDN for more.

justifyItemsstring β”‚ { "xs": "string", "sm": "string", "md": "string", "lg": "string", "xl": "string", "x2l": "string", "x3l": "string" }undefinedfalse

Items justification. Accepts any valid value of justify-items CSS property. See MDN for more.

rowGap0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7 β”‚ { "xs": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7", "sm": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7", "md": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7", "lg": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7", "xl": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7", "x2l": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7", "x3l": "0 β”‚ 1 β”‚ 2 β”‚ 3 β”‚ 4 β”‚ 5 β”‚ 6 β”‚ 7" }4false

Gap between rows. Accepts any of spacing values as number. See MDN for more about row-gap.

rowsstring β”‚ { "xs": "string", "sm": "string", "md": "string", "lg": "string", "xl": "string", "x2l": "string", "x3l": "string" }'auto'false

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

tagstring"div"false

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 nameTypeDefaultRequiredDescription
childrennodenullfalse

Items to be aligned in the grid. If none are provided nothing is rendered.

columnsnumber β”‚ { "xs": "number", "sm": "number", "md": "number", "lg": "number", "xl": "number", "x2l": "number", "x3l": "number" }1false

Number of columns to span.

rowsnumber β”‚ { "xs": "number", "sm": "number", "md": "number", "lg": "number", "xl": "number", "x2l": "number", "x3l": "number" }1false

Number of rows to span.

tagstring"div"false

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