Skip to Content

React Responsive CSS Grid Component

Build responsive React CSS Grid layouts with auto-fit columns, theme spacing, and item placement. Explore Grid and GridItem examples and TypeScript props.

Use React Grid and GridItem components for responsive card collections, dashboards, and other two-dimensional layouts. They expose CSS Grid layout with theme-based spacing and optional explicit item placement.

Stable API maturity: Stable. The documented public API is covered by tests and is intended to remain backward-compatible within a major version. This is an API commitment, not a guarantee of production readiness in every application.

@puzzle-ui/ui requires React and React DOM ^19.0.0. Grid uses native CSS Grid without browser measurements or layout effects, so it can render on the server; framework integration requires React 19 support.

Import

import { Grid, GridItem } from "@puzzle-ui/ui";
import type { GridProps, GridItemProps } from "@puzzle-ui/ui";

Responsive columns

Grid uses native CSS Grid, not Flexbox. It defaults to one equal-width column, medium spacing, and stretched items. Like Stack, it supports as, theme gaps, and horizontal/vertical alignment. Use Stack for one-dimensional flex layouts; use Grid when columns and rows need to line up.

Ordinary children work directly: Grid renders only its root and never wraps or clones children. GridItem is optional and renders only the element you select. There are no layout effects, resize listeners, or client-only measurements.

390 × 844

Responsive props accept a scalar or { mobile, tablet?, desktop? }. Mobile is required in objects. Values inherit independently at larger breakpoints: mobile is the base, tablet starts at 768px, and desktop starts at 1024px. These are viewport breakpoints, not container queries.

Auto-fit to the available space

Use minChildWidth to create as many columns as fit the container, without choosing breakpoints. Remaining space is shared equally. The minimum is clamped to the container width so narrow containers do not overflow just to meet it. minChildWidth takes precedence over columns when both are supplied.

390 × 844

Spanning and placement

Use GridItem only where a child needs its own placement or alignment. Choose a semantic element or an existing component with as instead of adding a wrapper around it.

390 × 844

colSpan="full" spans from line 1 to -1 of the explicit columns. Numeric spans must fit the available columns at each breakpoint unless you intentionally want implicit tracks. colStart and rowStart accept positive or negative CSS grid line numbers, or "auto". An explicit colStart overrides the start line normally selected by colSpan, including "full".

For unequal tracks, named lines, areas, or advanced layouts, pass CSS track strings and standard styles:

<Grid
  columns="minmax(0, 2fr) minmax(0, 1fr)"
  rows="auto 1fr"
  rowGap="lg"
  columnGap="sm"
  style={{ gridAutoRows: "minmax(4rem, auto)", alignContent: "start" }}
>
  <GridItem colStart={2} rowStart={1} rowSpan={2}>
    Sidebar
  </GridItem>
  <article>Main content</article>
</Grid>

Grid API

All layout props below accept responsive values.

PropTypeDefaultDescription
columnsnumber | string1Positive integer for equal tracks, or a CSS grid-template-columns string.
rowsnumber | string"none"Positive integer for equal tracks, or a CSS grid-template-rows string. Implicit rows size to content by default.
minChildWidthstring-CSS length for auto-fit columns; overrides columns.
gap"0" | "xs" | "sm" | "md" | "lg" | "xl""md"Theme spacing for both axes.
rowGap, columnGapSame as gapgapIndependent axis spacing. An axis override replaces gap for that axis at all breakpoints.
alignH"start" | "center" | "end" | "stretch""stretch"Horizontal item alignment (justify-items).
alignVSame as alignH"stretch"Vertical item alignment (align-items).
autoFlowCSS grid-auto-flow"row"Auto-placement direction; supports "column", "dense", "row dense", and "column dense".

as defaults to "div" and is not responsive. Native props, event handlers, className, style, and React 19 ref are forwarded to that root, with types matching the selected element or component. Custom components must forward these props and render a layout-capable element. User styles take precedence over component layout styles.

GridItem API

All placement and alignment props accept responsive values.

PropTypeDefaultDescription
colSpannumber | "full"1Positive column span, or all explicit columns.
rowSpannumber1Positive row span.
colStart, rowStartnumber | "auto""auto"Non-zero integer grid line. Full-column spans start at 1 unless overridden.
alignH"auto" | "start" | "center" | "end" | "stretch""auto"Per-item horizontal alignment (justify-self).
alignVSame as alignH"auto"Per-item vertical alignment (align-self).

GridItem also accepts as (default "div") and native props, styles, classes, and refs matching that element. It must be a direct grid child for placement to apply. Custom CSS placement is also available on ordinary children through style={{ gridColumn: "1 / -1" }}.

Numeric counts and spans must be positive integers; start lines must be non-zero integers. Invalid numbers throw a RangeError, including in responsive values. CSS strings are passed to the browser unchanged and must be valid CSS.

Accessibility

Grid adds no ARIA role or keyboard interaction. A visual CSS grid is not an ARIA grid widget. Use semantic content such as as="ul" with GridItem as="li", and preserve meaningful reading and focus order.

Explicit placement and dense auto-flow can change visual order without changing DOM or keyboard order; avoid them when that would make content confusing. start and end follow the document's writing direction, including RTL. Long content can overflow its cell; choose wrapping or scrolling on that content when necessary. Grid does not hide overflow.