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
Field
Type
Default
What it does
columnscolumns
number1–50step 1
—
How many columns
Divides the width of the tab or group into this many equal columns, 1 to 50.
rowsrows
number1–50step 1
—
How many rows
Divides the grid into this many rows, 1 to 50.
modemode
text
—
Grid or flow layout
Chooses a true 2-D grid (the default) or the older flow layout that stacks children in row bands.
rowHeightrowHeight
number12–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.
spacingspacing
number0–32 ptstep 1
8
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.
scalescale
number0.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.
reflowreflow
text
—
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.
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.
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.
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:
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.
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.
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.
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):
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.