Guide / Controls / Reference

Grid Dimensions

Every tab and every group lays its children out on a grid of columns × rows. A child declares where it sits with position: [row, col] and how many cells it covers with span: [rowSpan, colSpan] (see Shadow opacity).

Symbol
square.grid.3x3
Docs
Docs complete

Fields

7 fields, each with what it does.

Fields
FieldTypeDefaultWhat it does
columnscolumnsnumber1–50step 1—

How many columns

Divides the width of the tab or group into this many equal columns, 1 to 50.

rowsrowsnumber1–50step 1—

How many rows

Divides the grid into this many rows, 1 to 50.

modemodetext—

Grid or flow layout

Chooses a true 2-D grid (the default) or the older flow layout that stacks children in row bands.

rowHeightrowHeightnumber12–200step 1—

How tall one row is

Sets the points one row-unit takes in 2-D mode, default 56; auto makes each row as tall as its content needs.

spacingspacingnumber0–32 ptstep 18

The gap between controls

Sets the gap between the grid's cells, 0 to 32 points; 0 butts the controls together, and Default goes back to the theme's 8. A scaled grid's gaps shrink with its controls.

scalescalenumber0.3–1.5step 0.05—

Shrink or grow the controls

Draws this grid's controls proportionally smaller or larger, 0.3 to 1.5; auto follows the group's shape, so a 1 by 5 group holding a 3 by 15 grid draws them at a third.

reflowreflowtext—

How landscape re-packs the tab

Auto doubles the columns and re-packs the children in landscape; stretch keeps the portrait cells and makes them wider.

Examples

4 examples, each one a control you can paste into a layout.

Compact list card with auto rows

Demonstrates rowHeight: "auto" with scale: "auto": a one-row card whose rows size to their content.

JSON 5 lines
{ "grid": { "columns": 15, "rows": 3, "rowHeight": "auto", "scale": "auto" },
  "children": [
    { "type": "label", "id": "title", "position": [0, 0], "span": [1, 10], "label": "Water pump" },
    { "type": "button", "id": "go", "position": [0, 10], "span": [1, 5], "label": "Run" }
  ] }

Roomier gaps on a card row

Demonstrates spacing: 16: the same three cards with twice the theme's gap between them.

JSON 6 lines
{ "grid": { "columns": 3, "rows": 2, "spacing": 16 },
  "children": [
    { "type": "statTile", "id": "in", "position": [0, 0], "span": [2, 1], "label": "Inside" },
    { "type": "statTile", "id": "out", "position": [0, 1], "span": [2, 1], "label": "Outside" },
    { "type": "statTile", "id": "hum", "position": [0, 2], "span": [2, 1], "label": "Humidity" }
  ] }

Flow mode for a full-page map

Demonstrates mode: "flow": children stack in row bands and controlHeight sets the height.

JSON 4 lines
{ "grid": { "columns": 4, "rows": 2, "mode": "flow" },
  "children": [
    { "type": "map", "id": "site", "position": [0, 0], "span": [1, 4], "controlHeight": 480 }
  ] }

Landscape stretch with a taller row unit

Demonstrates rowHeight: 64 and reflow: "stretch": the portrait cells stay and only grow wider when the phone turns sideways.

JSON 4 lines
{ "grid": { "columns": 4, "rows": 6, "rowHeight": 64, "reflow": "stretch" },
  "children": [
    { "type": "map", "id": "area", "position": [0, 0], "span": [6, 4] }
  ] }
"grid": { "columns": 4, "rows": 6 }

Modes

mode Layout Best for
"grid" (default) True 2-D. Each child occupies a real row × col rectangle. Columns divide the width evenly; rows are a fixed rowHeight unit. A child can span both axes, so a tall control can sit beside two stacked shorter ones (masonry / L-shapes). Dashboards and mixed screens — gauges, rings, inputs, maps together.
"flow" Legacy row-banded. Children are grouped by their row index into horizontal bands; colSpan sets proportional width but heights are natural (or controlHeight). rowSpan is ignored. Full-page content (a single map / chat / cardList filling the tab) and pure forms where natural heights read best.

mode is optional — omit it for the default 2-D grid. Set "flow" to opt a tab or group out.

"grid": { "columns": 4, "rows": 8, "mode": "flow" }

How spans map to size

2-D ("grid") "flow"
colSpan (width) colSpan / columns of the row width colSpan / columns of the row width
rowSpan (height) rowSpan × rowHeight points ignored — height is natural / controlHeight

So in 2-D a 1×1 cell is genuinely small, and you make a control bigger by spanning more cells. Visual controls scale all of their internals (stroke, glyph, font) to the cell they're given — a small ring is tight and legible, a large ring is bold.

rowHeight

The height of one row-unit, in points (2-D mode only; default 56). One unit is a comfortable input row, so:

  • inputs (slider, toggle, segmentedControl, …) sit in 1 row,
  • a square control (progressRing, full gauge) wants ~3 rows to read square,
  • tall content (map, list, graph, image) spans as many rows as you give it.
"grid": { "columns": 4, "rows": 10, "rowHeight": 64 }

rowHeight: "auto"

Instead of a number, "rowHeight": "auto" makes every row as tall as the tallest one-row child that starts in it needs (each child measured at its column width, capped at two row-units). A taller multi-row child grows its last row to fit. Rows nothing starts in take no height. Use it on a list itemTemplate grid so a one-row card (icon, a label with a subtitle, a button) stays compact instead of using fixed 56-pt units:

"itemTemplate": { "grid": { "columns": 4, "rows": 1, "rowHeight": "auto" }, "children": [ … ] }

spacing

The gap between neighbouring cells, across and down, in points (default 8, the theme's grid gap). It applies to every grid: a tab, a group, a container's page, a list itemTemplate row and an expanded group. A child spanning several cells also covers the gaps between them, so with the default a 2-row control is 2 × rowHeight + 8 tall (the 64n - 8 rule in Style Rules). 0 butts the controls together; a grid with a scale draws its gaps at that scale too, so a miniature keeps its proportions.

"grid": { "columns": 4, "rows": 6, "spacing": 12 }

scale

scale draws the controls on this grid as proportional miniatures: fonts, padding, spacing, corners, icons and control sizes shrink (or grow) together through the theme, and touch targets stay 44 pt. A number is the factor (0.3 to 1.5). "auto" follows the group's shape: the smaller of its span rows / grid rows and span columns / grid columns, at most 1, and each row is that factor times the page's row. A group 1 × 5 on its page with a 3 × 15 grid draws at 1/3, so three 1 × 1 controls stack in its one row and each looks like a 1 × 1 outside at a third of the size. A list row counts as one row cell. With a rowHeight number "auto" keeps rowHeight / 56; with rowHeight: "auto" it is 1. A grid nested in a scaled grid scales with it. Details and an example: Scale.

"grid": { "columns": 15, "rows": 3, "scale": "auto" }

Sizing a control

You usually don't set a height at all — in 2-D the cell (rowSpan × rowHeight) is the height, and in flow shaped controls auto-size to their natural aspect. controlHeight (see Shadow opacity) is an override for the rare case you want an exact point height regardless of the grid.

Example — a 2-D dashboard with an L-shape

{
  "grid": { "columns": 4, "rows": 5 },
  "children": [
    { "type": "progressRing", "id": "cpu", "position": [0, 0], "span": [3, 2], "label": "CPU" },
    { "type": "gauge",        "id": "mem", "position": [0, 2], "span": [2, 2], "label": "Memory" },
    { "type": "statusLight",  "id": "net", "position": [2, 2], "span": [1, 2], "label": "Uplink" }
  ]
}

The CPU ring is a tall 2×2-plus block on the left; Memory and the Uplink light stack to its right — placement that the flow renderer can't express.

Landscape and iPad

A page picks its presentation from the size classes:

Presentation When What renders
default a phone held upright, a narrow iPad tile each child's position / span — always exactly as authored
landscape compact height (any iPhone on its side) the tab re-packs (below), then any landscape variant
regular regular width and height (iPad full screen or a wide tile) the declared cells, then any regular variant

reflow: "auto" (the default) makes landscape use the extra width for more of the dashboard instead of stretched slabs: the tab's grid doubles its columns (two portrait pages side by side) and every child is re-packed in reading order (row, then col), spans kept, first free cell from the top-left. A child that spanned the whole portrait width and has nothing to its right widens to the new edge. reflow: "stretch" keeps the portrait cells, only wider — right for a page that is one big map or list.

An author overrides one child per presentation with a variant — inline on the child or in the document's placements section (see Document Contract):

"placements": {
  "map":  { "landscape": { "position": [0, 4], "span": [5, 4] } },
  "hint": { "landscape": { "hidden": true } },
  "ring": { "regular":   { "position": [1, 2], "span": [2, 2] } }
}
  • A variant with position is placed exactly there (its span, else the default span). In landscape auto, its coordinates are in the doubled grid and the other children pack around it.
  • span alone keeps the child's packed slot (landscape auto) or its declared position (stretch / regular) and changes its size.
  • hidden: true leaves the child out of that presentation.
  • Only a tab's own grid re-packs; groups and mode: "flow" grids keep their cells (variants on a group's children still apply, flow grids ignore them).
  • The default presentation never reads a variant, so portrait is unchanged.

Generated from ControlDocs/grid-dimensions.md. Something unclear or missing? Tell me.