Grid

alpha RSC
Utilize a versatile layout tool for creating grid-based UIs with rows and columns. Flexible and robust for diverse layout structures.
Installation
API Reference
Examples
Important Note
This is the documentation for gluestack-ui v2 (beta). For @gluestack-ui/themed (stable) documentation, refer to gluestack-ui v1.
This is an illustration of Grid component.
<Grid
className="gap-5"
_extra={{
className: "grid-cols-8",
}}
>
<GridItem
className="bg-background-50 p-6 rounded-md"
_extra={{
className: "col-span-3",
}}
/>
<GridItem
className="bg-background-50 p-6 rounded-md"
_extra={{
className: "col-span-5",
}}
/>
<GridItem
className="bg-background-50 p-6 rounded-md"
_extra={{
className: "col-span-6",
}}
/>
<GridItem
className="bg-background-50 p-6 rounded-md"
_extra={{
className: "col-span-4",
}}
/>
<GridItem
className="bg-background-50 p-6 rounded-md"
_extra={{
className: "col-span-4",
}}
/>
</Grid>

Installation

Run the following command:

npx gluestack-ui add grid

API Reference

To use this component in your project, include the following import statement in your file.
import { Grid, GridItem } from "@/components/ui/grid"
export default () => (
<Grid>
<GridItem />
</Grid>
)
Important Note
Note: Our responsive grid component is based on a 12-column grid layout. It follows the CSS grid system on the web and flexbox layout on native devices. Since the grid layout is only supported on the web, passing the grid-cols and col-span classNames inside _extra is recommended for the grid component to work effortlessly on both web and native. Our grid component currently does not support rowSpan.

Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

Grid

Renders a <div /> on web and a View on native.

Platform
Output
Web
<div />
Native
<View />

props

Prop
Type
Default
Description
_extra
object
-
Accepts grid-cols-* className. Value for * can range from 1 to 12. Default value is grid-cols-12.

GridItem

Renders a <div /> on web and a View on native.

Platform
Output
Web
<div />
Native
<View />

props

Prop
Type
Default
Description
_extra
object
-
Accepts col-span-* className. Value for * can range from 1 to 12. Default value is col-span-1.

Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

Setting the gap between grid items

Use the gap-* utilities to change the gap between both rows and columns in grid
<Grid
className="gap-4"
_extra={{
className: "grid-cols-9",
}}
>
<GridItem
className="bg-background-50 p-3 rounded-md text-center"
_extra={{
className: "col-span-3",
}}
>
<Text>A</Text>
</GridItem>
<GridItem
className="bg-background-50 p-3 rounded-md text-center"
_extra={{
className: "col-span-3",
}}
>
<Text>B</Text>
</GridItem>
<GridItem
className="bg-background-50 p-3 rounded-md text-center"
_extra={{
className: "col-span-3",
}}
>
<Text>C</Text>
</GridItem>
</Grid>

Changing row and column gaps independently

Use the gap-x-* and gap-y-* utilities to change the gap between columns and rows independently.
<Grid
className="gap-y-2 gap-x-4"
_extra={{
className: "grid-cols-6",
}}
>
<GridItem
className="bg-background-50 p-4 rounded-md text-center"
_extra={{
className: "col-span-2",
}}
>
<Text className="text-sm">01</Text>
</GridItem>
<GridItem
className="bg-background-50 p-4 rounded-md text-center"
_extra={{
className: "col-span-2",
}}
>
<Text className="text-sm">02</Text>
</GridItem>
<GridItem
className="bg-background-50 p-4 rounded-md text-center"
_extra={{
className: "col-span-2",
}}
>
<Text className="text-sm">03</Text>
</GridItem>
<GridItem
className="bg-background-50 p-4 rounded-md text-center"
_extra={{
className: "col-span-2",
}}
>
<Text className="text-sm">04</Text>
</GridItem>
<GridItem
className="bg-background-50 p-4 rounded-md text-center"
_extra={{
className: "col-span-2",
}}
>
<Text className="text-sm">05</Text>
</GridItem>
<GridItem
className="bg-background-50 p-4 rounded-md text-center"
_extra={{
className: "col-span-2",
}}
>
<Text className="text-sm">06</Text>
</GridItem>
</Grid>

Nested Grids

The following example depicts how easily you can nest grids to create complex layouts with multiple levels of nesting.
<Grid
className="gap-3"
_extra={{
className: "grid-cols-8",
}}
>
<GridItem
className="bg-background-50 p-3 rounded-md text-center"
_extra={{
className: "col-span-4",
}}
>
<Text className="text-sm">01</Text>
</GridItem>
<GridItem
className="bg-background-50 p-3 rounded-md text-center"
_extra={{
className: "col-span-4",
}}
>
<Text className="text-sm">02</Text>
</GridItem>
<GridItem
className="bg-background-50 p-3 rounded-md text-center"
_extra={{
className: "col-span-4",
}}
>
<Grid
className="gap-5"
_extra={{
className: "grid-cols-2",
}}
>
<GridItem
className="bg-background-200 p-2 rounded-md"
_extra={{
className: "col-span-1",
}}
>
<Text className="text-sm">1</Text>
</GridItem>
<GridItem
className="bg-background-200 p-2 rounded-md"
_extra={{
className: "col-span-1",
}}
>
<Text className="text-sm">2</Text>
</GridItem>
<GridItem
className="bg-background-200 p-2 rounded-md"
_extra={{
className: "col-span-1",
}}
>
<Text className="text-sm">3</Text>
</GridItem>
<GridItem
className="bg-background-200 p-2 rounded-md"
_extra={{
className: "col-span-1",
}}
>
<Text className="text-sm">4</Text>
</GridItem>
</Grid>
</GridItem>
<GridItem
className="bg-background-50 p-3 rounded-md text-center"
_extra={{
className: "col-span-4",
}}
>
<Grid
className="gap-5"
_extra={{
className: "grid-cols-4",
}}
>
<GridItem
className="bg-background-200 p-2 rounded-md"
_extra={{
className: "col-span-4",
}}
>
<Text className="text-sm">1</Text>
</GridItem>
<GridItem
className="bg-background-200 p-2 rounded-md"
_extra={{
className: "col-span-4",
}}
>
<Text className="text-sm">2</Text>
</GridItem>
</Grid>
</GridItem>
</Grid>

Responsive Grids

You can pass different grid-cols-* and col-span-* values at different breakpoints to create a more responsive layout.
<Grid
className="gap-y-2 gap-x-4"
_extra={{
className: "grid-cols-6",
}}
>
<GridItem
className="bg-background-50 p-4 rounded-md text-center"
_extra={{
className: "col-span-6 md:col-span-3 lg:col-span-2",
}}
>
<Text className="text-sm">01</Text>
</GridItem>
<GridItem
className="bg-background-50 p-4 rounded-md text-center"
_extra={{
className: "col-span-6 md:col-span-3 lg:col-span-2",
}}
>
<Text className="text-sm">02</Text>
</GridItem>
<GridItem
className="bg-background-50 p-4 rounded-md text-center"
_extra={{
className: "col-span-6 md:col-span-3 lg:col-span-2",
}}
>
<Text className="text-sm">03</Text>
</GridItem>
<GridItem
className="bg-background-50 p-4 rounded-md text-center"
_extra={{
className: "col-span-6 md:col-span-3 lg:col-span-2",
}}
>
<Text className="text-sm">04</Text>
</GridItem>
<GridItem
className="bg-background-50 p-4 rounded-md text-center"
_extra={{
className: "col-span-6 md:col-span-3 lg:col-span-2",
}}
>
<Text className="text-sm">05</Text>
</GridItem>
<GridItem
className="bg-background-50 p-4 rounded-md text-center"
_extra={{
className: "col-span-6 md:col-span-3 lg:col-span-2",
}}
>
<Text className="text-sm">06</Text>
</GridItem>
</Grid>

Why we introduced _extra prop?

Grid Layout is not supported in native. In order to make our component universal, we introduced the _extra prop to pass the grid classnames to the grid component. We use the _extra prop to pass the grid classnames to the grid component & extract the neccessary styles from the provided classname. This approach provides a SSR friendly solution for responsiveness.