---
title: Grid List
description: Grid List
---

Field-level catalog tables below stay in English — they match the machine design schema used by the editor, API, and MCP.

Decoration and visibility use [Decoration & visibility (BlockShell)](/en/design/shared-concepts/block-shell).

> Preferred CSS grid for slot children (no cells array). Editor `gridLayout` writes columns/gaps/alignment per breakpoint. Items control writes itemOrderByChildId, columnSpanByChildId, and rowSpanByChildId keyed by child Puck id. Prefer over legacy GridBlock for new designs (including email chrome). Email approximates column spans in tables and ignores CSS order / rowspan.

## Fields

### `content`

Main content payload. Shape depends on the block: nested slot blocks, rich-text HTML, or body copy.

```
content: []
```

### `gridLayout`

_Editor-only control — does not persist its own value._

Editor-only control. Persists columnsByBreakpoint, columnGapByBreakpoint, rowGapByBreakpoint, and alignment maps — not a stored gridLayout string.

```
columnsByBreakpoint: { desktop: 3 }
columnGapByBreakpoint: { mobile: 16, desktop: 24 }
rowGapByBreakpoint: { mobile: 16, desktop: 24 }
```

### `itemsEditor`

_Editor-only control — does not persist its own value._

Editor-only Items control. Writes itemOrderByChildId, columnSpanByChildId, rowSpanByChildId.

```
itemOrderByChildId: { "HeadingBlock-1": { desktop: 1 } }
columnSpanByChildId: { "HeadingBlock-1": { desktop: 2 } }
rowSpanByChildId: { "HeadingBlock-1": { desktop: 1 } }
```

### `layout`

#### `itemOrderByChildId`

Map of child Puck id → breakpoint id → CSS order. Web-only.

```
layout: {
  itemOrderByChildId: { "HeadingBlock-1": { mobile: 2, desktop: 0 } }
}
```

#### `columnSpanByChildId`

Map of child Puck id → breakpoint id → column span (1–12).

```
layout: {
  columnSpanByChildId: { "HeadingBlock-1": { desktop: 2 } }
}
```

#### `rowSpanByChildId`

Map of child Puck id → breakpoint id → row span (1–12). Web-only.

```
layout: {
  rowSpanByChildId: { "HeadingBlock-1": { desktop: 2 } }
}
```

<details><summary>Default props</summary>

```json
{
  "content": [],
  "layout": {
    "columnsByBreakpoint": {},
    "columnGapByBreakpoint": {
      "mobile": 16,
      "desktop": 16
    },
    "rowGapByBreakpoint": {
      "mobile": 16,
      "desktop": 16
    },
    "justifyItemsByBreakpoint": {},
    "alignItemsByBreakpoint": {},
    "justifyContentByBreakpoint": {},
    "alignContentByBreakpoint": {}
  },
  "shell": {
    "customizeEnabled": false,
    "pointerEvents": "auto",
    "decorationBySelector": {},
    "visibility": {
      "showOnBreakpoints": {},
      "showOnLocales": {},
      "authVisibility": "all",
      "routeLockVisibility": "all",
      "roleVisibility": [],
      "entryActionVisibility": "all",
      "queryPageVisibility": "all",
      "hideWhenEmpty": ""
    },
    "anchor": {
      "anchorId": "",
      "anchorKey": ""
    },
    "box": {
      "padding": "none",
      "paddingEnabled": false,
      "marginsEnabled": false,
      "sizeByBreakpoint": {},
      "positionEnabled": false,
      "positionByBreakpoint": {}
    },
    "background": {
      "backgroundEnabled": false,
      "backgroundWidth": "page",
      "backgroundKind": "solid",
      "backgroundColorLight": "",
      "backgroundColorDark": "",
      "gradientType": "linear",
      "gradientAngle": 180,
      "gradientColors": [
        {
          "light": "",
          "dark": "",
          "offset": 50
        },
        {
          "light": "",
          "dark": "",
          "offset": 50
        }
      ],
      "gradientColor1Light": "",
      "gradientColor1Dark": "",
      "gradientColor2Light": "",
      "gradientColor2Dark": "",
      "backgroundImageSrc": "",
      "backgroundImageMode": "cover",
      "backgroundRepeatSize": 100,
      "backgroundPosition": "center",
      "backgroundMotionEnabled": false,
      "backgroundMotionDirectionDeg": 0,
      "backgroundMotionSpeed": 20,
      "backgroundMotionRotateDegPerSec": 0,
      "backgroundVideoSrc": "",
      "backgroundVideoFit": "cover",
      "backgroundVideoLoop": true,
      "backgroundVideoRepeatSize": 100,
      "backgroundAnimationMode": "particle",
      "backgroundAnimShape": "circle",
      "backgroundAnimSvgSrc": "",
      "backgroundAnimColorMode": "solid",
      "backgroundAnimColorLight": "#ffffff88",
      "backgroundAnimColorDark": "#ffffff66",
      "backgroundAnimSize": 12,
      "backgroundAnimJitter": 0.2,
      "backgroundParticleCount": 40,
      "backgroundParticleLifetimeSec": 4,
      "backgroundParticleSpeed": 40,
      "backgroundParticleAnimType": "fade",
      "backgroundParticleFromSide": "left",
      "backgroundParticleToSide": "right",
      "backgroundGridStyle": "cells",
      "backgroundGridMotionDirectionDeg": 0,
      "backgroundGridMotionSpeed": 0,
      "backgroundGridRotateDegPerSec": 0,
      "backgroundGridHoverGrowLimitPct": 50,
      "backgroundGridHoverRotateLimitDeg": 0,
      "backgroundGridReactionTimeSec": 1,
      "backgroundGridHoverGrow": true,
      "backgroundGridHoverRotate": false,
      "backgroundGridHoverColor": false,
      "backgroundGridHoverColorLight": "#ffffff55",
      "backgroundGridHoverColorDark": "#ffffff33",
      "backgroundGridReactionSpeed": 1,
      "backgroundBackdropEnabled": false,
      "backgroundBackdropBlurPx": 0,
      "backgroundBackdropBrightness": 1,
      "backgroundBackdropContrast": 1,
      "backgroundBackdropSaturate": 1,
      "backgroundBackdropGrayscale": 0,
      "backgroundBackdropSepia": 0,
      "backgroundBackdropHueRotateDeg": 0
    },
    "border": {
      "borderEnabled": false,
      "borderColorLight": "",
      "borderColorDark": "",
      "borderStyle": "solid"
    },
    "shadow": {
      "shadowEnabled": false,
      "shadowValueLight": "",
      "shadowValueDark": ""
    },
    "effects": {
      "effectsEnabled": false,
      "opacity": 1,
      "filterBlurPx": 0,
      "filterBrightness": 1,
      "filterContrast": 1,
      "filterSaturate": 1,
      "filterGrayscale": 0,
      "filterSepia": 0,
      "filterHueRotateDeg": 0,
      "filterDropShadowOffsetX": 0,
      "filterDropShadowOffsetY": 0,
      "filterDropShadowBlur": 0,
      "filterDropShadowColorLight": "",
      "filterDropShadowColorDark": "",
      "mixBlendMode": "normal"
    },
    "scrollAnimation": {
      "scrollAnimationEnabled": false,
      "scrollAnimationType": "fadeIn",
      "scrollAnimationDuration": 600,
      "scrollAnimationDelay": 0
    },
    "cursorTilt": {
      "cursorTiltEnabled": false,
      "cursorTiltIntensity": 12
    },
    "wander": {
      "wanderEnabled": false,
      "wanderSpeed": 40,
      "wanderJitter": 40,
      "wanderTurnRadius": 50,
      "wanderTurnSmoothness": 40,
      "wanderLimits": "parent"
    },
    "transform": {
      "transformEnabled": false,
      "transformRotateX": 0,
      "transformRotateY": 0,
      "transformRotateZ": 0,
      "transformTranslateX": 0,
      "transformTranslateY": 0,
      "transformTranslateZ": 0,
      "transformScale": 1
    }
  }
}
```

</details>