Grid

A <div> that lays out its children with CSS grid, plus a GridItem for per-item placement (column/row span or start/end, named areas, and self-alignment).

Installation

npm install @sipe-team/grid

import '@sipe-team/grid/styles.css';

Usage

Give Grid a templateColumns and gap; children fill the implicit grid in source order.

1

2

3

Examples

Named areas

templateAreas names regions of the grid; each GridItem claims one with a matching area.

Header

Sidebar

Main

Footer

Spanning columns and rows

colSpan/rowSpan are shorthand for grid-column/grid-row: span N.

rowSpan 2

colSpan 2

colSpan 1

colSpan 3

Explicit start/end

colStart/colEnd and rowStart/rowEnd build a start / end line range (each defaults to auto). They only take effect when column/row and colSpan/rowSpan are unset — see GridItem for the full priority order.

col 2 → 4

Item self-alignment

justifySelf/alignSelf on a GridItem position it within its own cell.

start

center

end

Nested grids

Grid nests freely — an inner Grid lays out independently of its parent.

Outer

Inner 1

Inner 2

asChild

Both Grid and GridItem support asChild to drop their wrapping <div> and merge onto the element you provide.

1

2

Anatomy

import { Grid, GridItem } from '@sipe-team/grid';

export default () => (
  <Grid templateColumns="repeat(3, 1fr)" gap="1rem">
    <GridItem colSpan={2}>Item</GridItem>
    <GridItem>Item</GridItem>
  </Grid>
);

Grid renders a single <div> (or the child element when asChild is set). GridItem is not required — any element works as a grid child — it only adds per-item placement props. @sipe-team/grid also exports Root and Item as aliases for Grid and GridItem, for a <Grid.Root>/<Grid.Item> compound-component import style (import * as Grid from '@sipe-team/grid').

API Reference

Grid

Renders a <div> (or the child element when asChild is set) and forwards its ref.

Prop	Type	Default	Description
templateColumns	CSSProperties['gridTemplateColumns']	—	grid-template-columns.
templateRows	CSSProperties['gridTemplateRows']	—	grid-template-rows.
templateAreas	CSSProperties['gridTemplateAreas']	—	grid-template-areas.
gap	CSSProperties['gap']	'0'	gap.
autoFlow	CSSProperties['gridAutoFlow']	'row'	grid-auto-flow.
inline	boolean	false	Uses inline-grid instead of grid.
asChild	boolean	false	Merge props onto the child instead of rendering a div.

Also accepts every ComponentProps<'div'> (className, style, onClick, …), forwarded to the rendered element. Grid also declares autoRows/autoColumns props (CSSProperties['gridAutoRows']/CSSProperties['gridAutoColumns']), but see Known limitations — they currently have no visual effect.

GridItem

Renders a <div> (or the child element when asChild is set) and forwards its ref.

Prop	Type	Default	Description
column	CSSProperties['gridColumn']	—	grid-column. Takes priority over colSpan and colStart/colEnd.
row	CSSProperties['gridRow']	—	grid-row. Takes priority over rowSpan and rowStart/rowEnd.
area	CSSProperties['gridArea']	—	grid-area, for placing into a named templateAreas region.
colSpan	number	—	Shorthand for grid-column: span N. Used only when column is unset.
rowSpan	number	—	Shorthand for grid-row: span N. Used only when row is unset.
colStart	number | 'auto'	—	Start line of grid-column. Used only when column and colSpan are unset.
colEnd	number | 'auto'	—	End line of grid-column. Used only when column and colSpan are unset.
rowStart	number | 'auto'	—	Start line of grid-row. Used only when row and rowSpan are unset.
rowEnd	number | 'auto'	—	End line of grid-row. Used only when row and rowSpan are unset.
justifySelf	CSSProperties['justifySelf']	—	justify-self.
alignSelf	CSSProperties['alignSelf']	—	align-self.
asChild	boolean	false	Merge props onto the child instead of rendering a div.

Also accepts every ComponentProps<'div'> (className, style, onClick, …), forwarded to the rendered element.

Known limitations

• Grid's autoRows and autoColumns props set internal CSS custom properties, but the compiled stylesheet never reads them back into grid-auto-rows/grid-auto-columns — passing either prop currently has no visual effect. Use style={{ gridAutoRows: ... }} / style={{ gridAutoColumns: ... }} as a workaround.
• Grid has no alignItems/justifyItems/alignContent/justifyContent props for container-level alignment, even though the stylesheet has unwired hooks for them internally. Use style={{ alignItems: ... }} etc. on Grid, or align individual children with GridItem's alignSelf/justifySelf.