Grid

A layout primitive for CSS grid — define columns, rows, template areas, and gaps with props instead of stylesheet rules.

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>

API Reference

Root

Renders a CSS grid container.

Prop

Type

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.

Prop

Type

Slots

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

SlotElement
gridThe grid container (or the element supplied via render)
grid-itemEach Grid.Item element

Examples

Basic Usage

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

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>

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.