Grid

Overview

Grid is a div with display: grid, exposing CSS grid through props: columns and rows (a number becomes repeat(n, 1fr), a string passes through as-is), templateAreas, autoFlow, gap/columnGap/rowGap, and the alignment props.

Reach for it when a layout runs in two dimensions at once — dashboards, card grids, page shells with named areas. For a single row or column, Flex is the simpler tool.

Children can be any elements. Wrap one in Grid.Item only when it needs its own placement or styling.

Anatomy

Import and assemble the component:

1import { Grid } from "@raystack/apsara";
2
3<Grid>
4  <Grid.Item />
5  <Grid.Item />
6</Grid>

Usage

Basic usage

A 2×2 grid defined with numeric rows and columns. Plain children and Grid.Item wrappers mix freely — both flow into cells in order.

Reach for Grid when the layout is two-dimensional: rows and columns that have to line up with each other. For a single row or column, Flex is simpler and needs no track definitions.

1<Grid gap={3} rows={2} columns={2}>
2  <Button>Button 1</Button>
3  <Button>Button 2</Button>
4  <Button>Button 3</Button>
5  <Grid.Item>4</Grid.Item>
6  <Grid.Item>5</Grid.Item>
7  <Grid.Item>6</Grid.Item>
8</Grid>

Spanning cells

colSpan and rowSpan let one item cover several tracks. Use them for the header and sidebar of a layout, where the shape of the page is the point rather than the order of the children.

1<Grid columns={3} gap={3}>
2  <Grid.Item
3    colSpan={3}
4    style={{
5      background: "var(--rs-color-background-base-primary-hover)",
6      border: "1px solid var(--rs-color-border-base-primary)",
7      borderRadius: 4,
8      padding: 12,
9      fontSize: 13,
10    }}
11  >
12    Header — colSpan 3
13  </Grid.Item>
14  <Grid.Item
15    rowSpan={2}

Template areas

templateAreas names regions and area places an item into one. Worth it when the layout has more than three or four regions — the names document the intent, and moving a region means editing one string rather than every child.

1<Grid
2  columns="140px 1fr"
3  gap={3}
4  templateAreas={["nav header", "nav main", "nav footer"]}
5>
6  <Grid.Item
7    area="nav"
8    style={{
9      background: "var(--rs-color-background-base-primary-hover)",
10      border: "1px solid var(--rs-color-border-base-primary)",
11      borderRadius: 4,
12      padding: 12,
13      fontSize: 13,
14    }}
15  >

Alignment

justifyItems and alignItems position every item inside its own cell. justifySelf and alignSelf override that for one item.

1<Grid columns={3} gap={3} rows="80px" alignItems="center" justifyItems="center">
2  <Grid.Item
3    style={{
4      background: "var(--rs-color-background-base-primary-hover)",
5      border: "1px solid var(--rs-color-border-base-primary)",
6      borderRadius: 4,
7      padding: 12,
8      fontSize: 13,
9    }}
10  >
11    centered
12  </Grid.Item>
13  <Grid.Item
14    alignSelf="start"
15    style={{

Automatic tracks

With no rows or columns, autoFlow decides which way items fill and autoColumns / autoRows size the tracks it creates. Use this when the number of items is not known ahead of time.

1<Grid autoFlow="column" autoColumns="minmax(90px, 1fr)" gap={3}>
2  <Grid.Item
3    style={{
4      background: "var(--rs-color-background-base-primary-hover)",
5      border: "1px solid var(--rs-color-border-base-primary)",
6      borderRadius: 4,
7      padding: 12,
8      fontSize: 13,
9    }}
10  >
11    1
12  </Grid.Item>
13  <Grid.Item
14    style={{
15      background: "var(--rs-color-background-base-primary-hover)",

API Reference

Root

Renders a CSS grid container.

Item

Grid.Item is a wrapper component that must be a direct child of Grid. Use it when you need to customize the positioning or styling of individual grid items.

Slots

Every rendered part carries a stable data-slot attribute for styling and testing:

Accessibility

• Renders a plain <div> and adds no roles or ARIA attributes — CSS grid is purely visual layout.
• Screen readers read children in DOM order. Explicit placement, templateAreas, and dense auto-flow can make the visual order differ from the reading order, so keep the DOM order meaningful.
• Use the render prop to swap in a semantic element (<ul>, <section>) when the grid represents a real group, such as a list of cards.