Grid

A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. For columns that reflow on small screens, use columns={{minWidth, max}}; a numeric columns is exactly N columns at every width and never reflows.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Grid

Prop	Type	Default	Description
columns	number \| {minWidth: number, max?: number, repeat?: 'fill' \| 'fit'}		Column configuration. A number is exactly N equal columns at every width and never reflows (e.g. `columns={3}`); for columns that reflow on small screens, use `{minWidth, max}`. Use an object for responsive columns: `minWidth` sets the minimum column width in px, `repeat` controls track behavior (`"fill"` preserves empty tracks for consistent widths, `"fit"` collapses empty tracks so items stretch; defaults to `"fill"`), and `max` caps the maximum number of columns.
width	SizeValue		Container width. Numbers are treated as pixels, strings are used as-is.
height	SizeValue		Container height. Numbers are treated as pixels, strings are used as-is.
maxWidth	SizeValue		Maximum container width. Numbers are treated as pixels, strings are used as-is.
minHeight	SizeValue		Minimum container height. Numbers are treated as pixels, strings are used as-is.
gap	0 \| 0.5 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10		Spacing between all items.
rowGap	0 \| 0.5 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10		Row spacing; overrides `gap` for the row axis.
columnGap	0 \| 0.5 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10		Column spacing; overrides `gap` for the column axis.
align	'start' \| 'center' \| 'end' \| 'stretch'	'stretch'	Vertical alignment of items.
justify	'start' \| 'center' \| 'end' \| 'stretch'	'stretch'	Horizontal alignment of items.
children	ReactNode		Grid content.
xstyle	StyleXStyles		StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.

Usage guidance

Default to responsive columns for anything that must survive a phone: columns={{minWidth: 240, max: 4}} renders at most 4 columns, each at least 240px, and drops to one full-width column when narrow.
Avoid: Use columns={4} for a row that must work on small screens; a number never reflows and renders four narrow tracks on a phone. Reserve numbers for rows that must stay fixed, such as a 7-day week.
Always pair minWidth with max: max caps the count on wide screens and lets the last column shrink to a narrow container; {minWidth} alone overflows a phone narrower than minWidth.
Use repeat: 'fill' (the default) for consistent item widths. Use 'fit' when items should stretch to fill leftover space.
Avoid: Write manual CSS grid; Grid handles spacing and responsive behavior for you.
Avoid: Use HStack with wrapping for grids; use Grid instead.
Track templates use CSS-variable indirection (not raw inline styles), so xstyle overrides of gridTemplateColumns (including inside @media queries) take effect.

Theming API

{
  "targets": [
    {
      "className": "astryx-grid",
      "visualProps": [
        "align",
        "columns",
        "gap",
        "justify"
      ]
    },
    {
      "className": "astryx-grid-span"
    }
  ]
}

GridSpan

Anatomy

Grid container: Two-dimensional layout container that arranges caller-supplied items in rows and columns.
Spanning item: Optional GridSpan wrapper that changes one item's column or row participation.

Grid Span

Grid item that spans multiple columns or rows.

Prop	Type	Description
columns	number \| 'full'	Columns to span; use `'full'` to span the entire row.
rows	number	Rows to span.
children	ReactNode	Content.

Examples

Grid:
Grid Span: GridSpan lets a grid item span multiple columns or rows within an Grid, enabling masonry-style and asymmetric layouts.
Grid — Dashboard Layout: Dashboard layout with mixed-size widgets and a full-width summary row
Grid — Card Gallery: Card gallery with responsive columns that maintain consistent widths
Grid — Responsive Auto-Fit: Responsive grid where cards stretch to fill remaining space
GridSpan — Columns: Grid items spanning two of three columns. Wrap a grid child in GridSpan to make it occupy multiple columns for asymmetric layouts.
Grid — Column Spanning: Grid with featured items spanning multiple columns and rows