Skip to main content

​
Description

The Grid component provides a powerful and flexible API for creating CSS Grid layouts. It supports all major grid properties including template areas, automatic column/row sizing, gap spacing, and alignment controls. The component also includes a companion GridItem component for positioning items within the grid.

​
Props

​
Grid

Grid extends all standard HTML div attributes through Base UI’s useRender hook and accepts the following props:
​
columns
string | number
Defines the grid template columns
  • When a number is provided, creates columns using repeat(n, 1fr)
  • When a string is provided, uses standard CSS Grid template syntax
<Grid columns={3} /> // Creates 3 equal columns
<Grid columns="1fr 2fr 1fr" /> // Custom column sizes
​
rows
string | number
Defines the grid template rows
  • When a number is provided, creates rows using repeat(n, 1fr)
  • When a string is provided, uses standard CSS Grid template syntax
<Grid rows={3} /> // Creates 3 equal rows
<Grid rows="auto 1fr auto" /> // Header, content, footer
​
templateAreas
string | string[]
Defines named grid areas using CSS Grid template areas syntax
  • Accepts a single string or an array of strings
  • Array format automatically adds quotes around each row
<Grid templateAreas="header header header" />
<Grid templateAreas={[
  "header header header",
  "sidebar main main",
  "footer footer footer"
]} />
​
autoFlow
'row' | 'column' | 'dense' | 'row dense' | 'column dense'
Controls how auto-placed items flow into the grid
  • row - Fill rows first
  • column - Fill columns first
  • dense - Fill holes in the grid
  • row dense - Fill rows first with dense packing
  • column dense - Fill columns first with dense packing
​
autoColumns
string
Defines the size of implicitly-created columns
<Grid autoColumns="minmax(100px, auto)" />
​
autoRows
string
Defines the size of implicitly-created rows
<Grid autoRows="minmax(50px, 1fr)" />
​
gap
'extra-small' | 'small' | 'medium' | 'large' | 'extra-large'
Controls spacing between all grid items
  • extra-small - Uses --rs-space-2
  • small - Uses --rs-space-3
  • medium - Uses --rs-space-5
  • large - Uses --rs-space-9
  • extra-large - Uses --rs-space-11
​
columnGap
'extra-small' | 'small' | 'medium' | 'large' | 'extra-large'
Controls spacing between columns only (same values as gap)
​
rowGap
'extra-small' | 'small' | 'medium' | 'large' | 'extra-large'
Controls spacing between rows only (same values as gap)
​
justifyItems
'start' | 'end' | 'center' | 'stretch'
Aligns grid items along the inline (row) axis
​
alignItems
'start' | 'end' | 'center' | 'stretch'
Aligns grid items along the block (column) axis
​
justifyContent
'start' | 'end' | 'center' | 'stretch' | 'space-around' | 'space-between' | 'space-evenly'
Aligns the grid along the inline (row) axis within its container
​
alignContent
'start' | 'end' | 'center' | 'stretch' | 'space-around' | 'space-between' | 'space-evenly'
Aligns the grid along the block (column) axis within its container
​
inline
boolean
default:"false"
When true, uses display: inline-grid instead of display: grid
​
style
React.CSSProperties
Additional inline styles (merged with grid styles)
​
className
string
Additional CSS class names to apply
​
render
(props: React.ComponentPropsWithRef<'div'>) => React.ReactElement
Custom render function from Base UI
​
ref
React.Ref<HTMLDivElement>
A ref to access the underlying div element

​
GridItem

GridItem is a companion component for positioning items within a Grid. It extends all standard HTML div attributes.
​
area
string
The name of the grid area to place this item in (must match a templateAreas name)
<GridItem area="header">Header content</GridItem>
​
colStart
number | string
The grid column line where the item starts
​
colEnd
number | string
The grid column line where the item ends
​
rowStart
number | string
The grid row line where the item starts
​
rowEnd
number | string
The grid row line where the item ends
​
colSpan
number | string
How many columns the item should span
<GridItem colSpan={2}>Spans 2 columns</GridItem>
​
rowSpan
number | string
How many rows the item should span
​
justifySelf
'start' | 'end' | 'center' | 'stretch'
Aligns this item along the inline (row) axis
​
alignSelf
'start' | 'end' | 'center' | 'stretch'
Aligns this item along the block (column) axis

​
Usage examples

​
Basic grid with numeric columns

import { Grid } from '@raystack/apsara';

function Example() {
  return (
    <Grid columns={3} gap="medium">
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
    </Grid>
  );
}

​
Custom column sizes

import { Grid } from '@raystack/apsara';

function Example() {
  return (
    <Grid columns="1fr 2fr 1fr" gap="small">
      <div>Sidebar</div>
      <div>Main content</div>
      <div>Sidebar</div>
    </Grid>
  );
}

​
Using template areas

import { Grid, GridItem } from '@raystack/apsara';

function Example() {
  return (
    <Grid
      templateAreas={[
        "header header header",
        "sidebar main main",
        "footer footer footer"
      ]}
      columns="200px 1fr 1fr"
      rows="auto 1fr auto"
      gap="medium"
    >
      <GridItem area="header">Header</GridItem>
      <GridItem area="sidebar">Sidebar</GridItem>
      <GridItem area="main">Main content</GridItem>
      <GridItem area="footer">Footer</GridItem>
    </Grid>
  );
}

​
Column and row spanning

import { Grid, GridItem } from '@raystack/apsara';

function Example() {
  return (
    <Grid columns={3} rows={2} gap="small">
      <GridItem colSpan={2}>Spans 2 columns</GridItem>
      <div>Regular item</div>
      <GridItem rowSpan={2}>Spans 2 rows</GridItem>
      <div>Item</div>
      <div>Item</div>
    </Grid>
  );
}

​
Auto-flow grid

import { Grid } from '@raystack/apsara';

function Example() {
  return (
    <Grid
      autoFlow="dense"
      autoColumns="minmax(100px, auto)"
      gap="medium"
    >
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
      <div>Item 4</div>
    </Grid>
  );
}

​
Responsive grid

import { Grid } from '@raystack/apsara';

function Example() {
  return (
    <Grid
      columns="repeat(auto-fit, minmax(250px, 1fr))"
      gap="large"
    >
      <div>Card 1</div>
      <div>Card 2</div>
      <div>Card 3</div>
      <div>Card 4</div>
    </Grid>
  );
}

​
Centered grid items

import { Grid } from '@raystack/apsara';

function Example() {
  return (
    <Grid
      columns={3}
      justifyItems="center"
      alignItems="center"
      gap="medium"
    >
      <div>Centered 1</div>
      <div>Centered 2</div>
      <div>Centered 3</div>
    </Grid>
  );
}

​
Different row and column gaps

import { Grid } from '@raystack/apsara';

function Example() {
  return (
    <Grid
      columns={3}
      rows={2}
      columnGap="large"
      rowGap="small"
    >
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
      <div>Item 4</div>
      <div>Item 5</div>
      <div>Item 6</div>
    </Grid>
  );
}

​
Styling notes

The Grid component applies inline styles directly to the element, making it highly flexible:
  • display: grid (or inline-grid when inline is true)
  • All grid properties are applied as inline styles
  • Custom styles passed via the style prop are merged with grid styles
The GridItem component also uses inline styles for grid placement properties:
  • gridArea, gridColumnStart, gridColumnEnd, gridRowStart, gridRowEnd
  • gridColumn and gridRow for span values
  • justifySelf and alignSelf for individual item alignment

​
Related components

  • Box - For basic container needs
  • Flex - For flexbox layouts
  • Container - For constrained-width containers