# Grid

- Page: https://jiguang132.com/resources/astryx/docs/grid
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## 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.

| 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

```json
{
  "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 | Default | 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

---

Index of all JGuang resources: https://jiguang132.com/llms.txt