Grid

Grid layout arranges children in 2D rows and columns, much like CSS Grid. Use it when content is naturally tabular or when you need a card grid with consistent cell sizes.

Note: this is the layout engine’s Grid. For a virtualised, scrollable grid of many items (like a long photo gallery), use the GridView component instead.

Quick start

AutoUI.Create().Grid().WidthFill().HeightHug()
    .GridColumns(3).Gap(8)
    .Children(
        AutoUI.Create().Height(80).Background(Color.red),
        AutoUI.Create().Height(80).Background(Color.green),
        AutoUI.Create().Height(80).Background(Color.blue),
        AutoUI.Create().Height(80).Background(Color.yellow)
    )
    .Build();

Three columns with 8px gap. Items flow left-to-right, top-to-bottom; the fourth item starts a new row.

Columns and rows

The fundamental setup: how many tracks does the grid have?

Property	Builder	Notes
Column count	`.GridColumns(n)`	0 = auto (one column)
Row count	`.GridRows(n)`	0 = auto (rows expand to fit)
Column gap	`.ColumnGap(8)`	Horizontal space between cells
Row gap	`.RowGap(8)`	Vertical space between cells
Both gaps	`.Gap(8)`	Sets both ColumnGap and RowGap at once

If you only set GridColumns(3) and don’t set GridRows, the grid expands rows as items overflow. Setting both creates a fixed grid that clips additional items.

Track sizes (the powerful part)

Instead of a count, you can specify per-track sizes as a string template — just like CSS Grid. Tracks can be pixels, fractions (1f, 2f), percentages, or auto-fit.

AutoUI.Create().Grid()
    .ColumnSizes("200 1f 1f")            // 200px sidebar, two equal-fraction columns
    .RowSizes("60 1f")                   // 60px header row, content row fills
    .Build();

Token	Meaning
`200`	Fixed pixels
`1f`, `2f`	Fractional unit (shares remaining space proportionally)
`25%`	Percentage of container
`auto`	Sized to content (intrinsic)
`repeat(3, 1f)`	`1f 1f 1f` — counted repeat
`repeat(3, 100 1f)`	`100 1f 100 1f 100 1f` — multi-track repeat
`repeat(auto-fit, minmax(200, 1f))`	Responsive: as many columns as fit, each ≥ 200px

Auto-fit columns

The most-used responsive pattern. Column count changes with container width.

AutoUI.Create().Grid().WidthFill()
    .GridAutoFit(200)                    // shorthand for repeat(auto-fit, minmax(200, 1f))
    .Gap(8)
    .Each(items, item => Card(item))
    .Build();

Or by percentage:

AutoUI.Create().Grid().WidthFill()
    .GridAutoFitPercent(25)              // at most 4 columns (each ≥ 25% of container)
    .Build();

Auto flow

How items fill empty cells when not explicitly placed:

Value	Effect
`Row` (default)	Fill row by row, left to right
`Column`	Fill column by column, top to bottom
`RowDense`	Like Row, but backfill earlier holes when a span doesn’t fit
`ColumnDense`	Like Column, but backfill

AutoUI.Create().Grid().GridColumns(4).GridFlow(GridAutoFlow.RowDense)
    .Children(...)
    .Build();

Dense flow is useful when items have spans (see below) and would otherwise leave gaps.

Cell alignment

How items sit within their cells:

Property	Builder	Default
Container — horizontal	`.GridHorizontalAlign(GridAlignment)`	`Stretch`
Container — vertical	`.GridVerticalAlign(GridAlignment)`	`Stretch`
Per-item — horizontal	`.GridItemHorizontalAlign(GridAlignment)`	`Auto` (inherit)
Per-item — vertical	`.GridItemVerticalAlign(GridAlignment)`	`Auto` (inherit)

GridAlignment values: Auto · Stretch · Start · Center · End. Default Stretch makes cells fill their grid track; switch to Start/Center/End for content-sized cells aligned within.

AutoUI.Create().Grid().GridColumns(3)
    .GridHorizontalAlign(GridAlignment.Center)        // all cells horizontally centered in their tracks
    .GridVerticalAlign(GridAlignment.Center)
    .Children(
        AutoUI.Create().Width(80).Height(80).Background(Color.red),
        AutoUI.Create().Width(80).Height(80).Background(Color.green)
            .GridItemHorizontalAlign(GridAlignment.End),     // override: pin to right of cell
        AutoUI.Create().Width(80).Height(80).Background(Color.blue)
    )
    .Build();

Item placement (explicit)

By default items auto-place. Override with explicit row/column:

AutoUI.Create().Grid().GridColumns(3).GridRows(3)
    .Children(
        AutoUI.Create()
            .GridColumn(0).GridRow(0)
            .Background(Color.red),
        AutoUI.Create()
            .GridColumn(2).GridRow(2)            // skip to bottom-right
            .Background(Color.green)
    )
    .Build();

Spans

A single item can span multiple columns or rows:

AutoUI.Create().Grid().GridColumns(3)
    .Children(
        AutoUI.Create().GridColumnSpan(2).Background(Color.red),    // spans 2 columns
        AutoUI.Create().Background(Color.green),
        AutoUI.Create().GridRowSpan(2).Background(Color.blue),      // spans 2 rows (next two slots)
        AutoUI.Create().Background(Color.yellow),
        AutoUI.Create().Background(Color.cyan)
    )
    .Build();

Combine spans with GridFlow.RowDense to backfill the gaps spans would otherwise leave.

Common patterns

Photo gallery (responsive)

AutoUI.Create().Grid().WidthFill()
    .GridAutoFit(160).Gap(8)
    .Each(photos, p =>
        AutoUI.Create().HeightAspect(1f)            // square cells
            .Background(p.Sprite))
    .Build();

Sidebar + content + inspector

AutoUI.Create().Grid().WidthFill().HeightFill()
    .ColumnSizes("200 1f 240")
    .RowSizes("1f")
    .Children(
        Sidebar(),
        Content(),
        Inspector()
    )
    .Build();

Form (label / field rows)

AutoUI.Create().Grid().WidthFill().HeightHug()
    .ColumnSizes("auto 1f")
    .Gap(8)
    .Each(fields, f => AutoUI.Create().Children(
        AutoUI.Create().TextSize().Text(f.Label),
        AutoUI.Create().WidthFill().Height(28)        // input field
    ))
    .Build();

The auto track sizes to the widest label; the 1f track fills remaining width.

Sizing — track sizing units explained
RowColumn — for simpler 1D layouts
GridView — virtualised grid for large datasets
AutoUI — builder reference