A highly responsive and flexible CSS Grid layout container for constructing grid-based page structures and interface layouts. Lay child elements out with an explicit column or row count, or let them auto-fit dynamically based on a minimum child width without needing explicit media queries. It fully supports responsive, per-breakpoint layout configurations.

---

Features

• Dynamic Columns & Rows: Effortlessly specify grid tracks using numeric values or custom CSS template definitions.
• Auto-Fit Scaling: Define a minimum child width threshold (minChildWidth) to let the container automatically flow children into columns as space permits.
• Responsive Breakpoints: Native support for responsive configurations across predefined system breakpoints (base, sm, md, lg, xl, 2xl).
• Polymorphic Rendering: Render as any semantic HTML tag via the as prop, or delegate grid styles onto a single child component via the asChild prop.
• Zero-Layout Shift Performance: Styles compile down to optimized, static Panda CSS utilities, avoiding client-side Javascript measurement overhead.

---

Usage

These examples illustrate how to structure grid components both in code (JSX/TSX) and via Page Builder JSON configurations.

1. Fixed Columns Structure

Specifies an explicit column count that displays three elements side-by-side. Excellent for feature grids, metric layouts, or navigation structures.

JSX / TSX

import { Grid } from "../components/ui";

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

Page Builder JSON

{
  "type": "grid",
  "columns": 3,
  "gap": "4",
  "children": [
    { "type": "text", "content": "1" },
    { "type": "text", "content": "2" },
    { "type": "text", "content": "3" }
  ]
}

---

2. Auto-Fit Columns by Minimum Width

Columns are added or dropped automatically as the screen resizes. This avoids the need to define breakpoints, ensuring fully responsive card containers out-of-the-box.

JSX / TSX

import { Grid } from "../components/ui";

export default function Example() {
  return (
    <Grid minChildWidth="120px" gap="4">
      <div>Card A</div>
      <div>Card B</div>
      <div>Card C</div>
    </Grid>
  );
}

Page Builder JSON

{
  "type": "grid",
  "minChildWidth": "120px",
  "gap": "4",
  "children": [
    { "type": "text", "content": "Card A" },
    { "type": "text", "content": "Card B" },
    { "type": "text", "content": "Card C" }
  ]
}

---

3. Responsive Column Allocation

Displays a single column on mobile screens, scales to two columns on tablets, and displays three columns on desktop.

Programmatic Usage (TSX)

import { Grid } from "@/components/ui";

export default function ResponsiveGrid() {
  return (
    <Grid columns={{ base: 1, md: 2, lg: 3 }} gap="6">
      <div>Responsive Grid Item 1</div>
      <div>Responsive Grid Item 2</div>
      <div>Responsive Grid Item 3</div>
    </Grid>
  );
}

Page Builder Configuration (CMS JSON)

JSX / TSX

import { Grid } from "../components/ui";

export default function Example() {
  return (
    <Grid columns={{ base: 1, md: 2, lg: 3 }} gap="6">
      <div>Responsive Grid Item 1</div>
      <div>Responsive Grid Item 2</div>
      <div>Responsive Grid Item 3</div>
    </Grid>
  );
}

Page Builder JSON

{
  "type": "grid",
  "columns": "{\"base\": 1, \"md\": 2, \"lg\": 3}",
  "gap": "6",
  "children": [
    { "type": "text", "content": "Responsive Grid Item 1" },
    { "type": "text", "content": "Responsive Grid Item 2" },
    { "type": "text", "content": "Responsive Grid Item 3" }
  ]
}

---

4. Separated Column & Row Gaps

Gaps between rows and columns can be configured independently to create asymmetrical grids or tighter row packaging.

JSX / TSX

import { Grid } from "../components/ui";

export default function Example() {
  return (
    <Grid columns={2} columnGap="6" rowGap="2">
      <div>1</div>
      <div>2</div>
      <div>3</div>
      <div>4</div>
    </Grid>
  );
}

Page Builder JSON

{
  "type": "grid",
  "columns": 2,
  "columnGap": "6",
  "rowGap": "2",
  "children": [
    { "type": "text", "content": "1" },
    { "type": "text", "content": "2" },
    { "type": "text", "content": "3" },
    { "type": "text", "content": "4" }
  ]
}

---

Props

Property	Type / CMS Field Type	Default	Description

| columns | number | string | Responsive<...> | - | Explicit column count (e.g. 3 or "3"). Can accept a breakpoint object or a JSON string in CMS (e.g., '{"base": 1, "md": 3}'). Has priority over minChildWidth. | | rows | number | string | Responsive<...> | - | Explicit row count. Useful for structured template layouts. | | minChildWidth | number | string | Responsive<...> | - | Width threshold for auto-fit columns (e.g., "120px", "16rem"). Ignored if columns is specified. | | gap | string | number | Responsive<...> | "8px" | Space separating consecutive cells. | | columnGap | string | number | Responsive<...> | - | Horizontal-only gap between grid columns. | | rowGap | string | number | Responsive<...> | - | Vertical-only gap between grid rows. |

| class | string | - | Custom CSS class overrides. |

| children | any | list | - | Collection of nested layout or visual blocks aligned inside the grid container. |

Responsive Values: Responsive<T> accepts a flat value or an object mapped by responsive breakpoints (e.g., { base: 1, md: 2, lg: 3 }). The design system supports the standard scale of breakpoints: base, sm, md, lg, xl, and 2xl.

---

Hydration & Architecture

Tier-3 Presentational Layout Primitive

The Grid component is classified as a Tier-3 Presentational Component under the project's Island Hydration architecture. It holds zero client-side reactive state and handles no event triggers. Consequently:

• It never mounts an interactive client-side island.
• It compiles directly to zero-JS static HTML, incurring absolutely zero bundle-size overhead.
• An explicit interactive prop is neither required nor supported.

Developer Implementation Notes

• Panda CSS Pattern Integration: Under the hood, this component translates columns, rows, and gap definitions into Panda CSS grid utility structures, generating high-performance atomic CSS classes.
• Responsive JSON Strings: When authoring pages within Sveltia CMS, responsive values (like breakpoint column configurations) should be written as JSON-serialised strings (e.g. '{"base": 1, "md": 2}'). These are automatically parsed and translated to breakpoint styles at runtime.

Accessibility Compliance

• Natural DOM Flow: The container preserves sequential keyboard navigation (Tab index) and DOM-tree reading orders. Ensure child element layouts align with logical visual sequences to keep document accessibility consistent for screen readers.