Documentation menu

grid

Lay out children in row-major tracks sized from their measured content.

Use grid(columns) -> Grid to align content in shared columns and rows. Children enter the grid in row-major order, filling the first row from left to right before continuing on the next row. The requested column count determines where each row begins.

Grid Construction

use hera_kit::{ViewExt, grid, text};

let facts = grid(2)
    .grid_spacing(24.0, 12.0)
    .child(text("Connection"))
    .child(text("Online"))
    .child(text("Documents"))
    .child(text("24"))
    .padding(16.0);

.grid_spacing(horizontal, vertical) sets independent gaps. .spacing(value) sets both gaps to the same value.

Track Sizing

The grid sizes a column to its widest measured child and a row to its tallest measured child. It then adds the configured spacing between tracks to determine each child's origin. As a result, cells in different rows can share column alignment even when their contents have different sizes.

This measurement makes the grid content-sized rather than dividing the parent's width into equal fractions. Children receive loosened parent constraints, and the final container remains bounded by the parent, but those bounds do not repartition oversized intrinsic tracks. Use suitable cell frames or a scroll viewport when the measured content can exceed the available region.

A zero column count is normalized to one by the layout implementation. Prefer a positive count in application code so the intended structure remains clear.

Repeated Cells

For repeated cells of one concrete view type, supply an iterator through .children(iterator). Stateful cells that can reorder also need stable keys so their state follows the item. Each child occupies one cell in this API; column spans, row spans, and adaptive track counts require a different arrangement.

Add ordinary authoring children directly in row-major order. The separate grid_row helper belongs to raw backend construction and is not exposed as a root-level public component.

See layout internals for shared track measurement and h_stack for a simpler single-row layout.

Component-Specific Reference

These methods configure the Grid returned by grid(columns). Each consumes the builder and returns Self, allowing configuration and child composition to be chained before common view modifiers wrap the container.

MethodPurpose
childAppends one child view.
maybe_childAppends a child only when the option contains a view.
childrenAppends an iterator of views with one concrete item type.
alignmentStores alignment; the current grid layout uses track origins for placement.
spacingSets the gap between adjacent children or tracks.
grid_spacingSets horizontal and vertical track gaps independently.

child

fn child(self, child: impl View) -> Self

Appends one child at the end of the current sequence. Successive calls may accept different concrete view types, making this the usual form for fixed interfaces that combine labels, controls, and nested containers. The declaration order determines the order in which children enter the layout.

maybe_child

fn maybe_child(self, child: Option<impl View>) -> Self

Appends the supplied view for Some(view) and leaves the builder unchanged for None. The absence does not create an empty placeholder or reserve spacing for an invisible child. When conditional content changes sibling positions, stable keys help stateful siblings retain the intended identity.

children

fn children<V: View>(self, children: impl IntoIterator<Item = V>) -> Self

Appends every item from the iterator in iteration order. All iterator items must share one concrete view type; heterogeneous fixed content can instead use successive child calls. The resulting hierarchy contains every supplied child, so this method does not introduce lazy construction or collection virtualization.

alignment

fn alignment(self, alignment: Alignment) -> Self

Stores the container’s alignment value through the shared container API. The current grid layout places each child at its measured track origin and does not use this value to align content within a cell. To center or edge-align a cell’s content, give that child a frame with its own alignment rather than relying on Grid::alignment.

spacing

fn spacing(self, spacing: f32) -> Self

Sets both horizontal and vertical gaps between tracks. The default is zero logical pixels. Spacing must be finite; negative values reduce separation and can make neighboring content overlap. It does not add an outer inset around the container, so use padding for that relationship. A later grid_spacing call can replace the two axis values independently.

grid_spacing

fn grid_spacing(self, horizontal: f32, vertical: f32) -> Self

Sets the horizontal gap between columns and the vertical gap between rows. Both values must be finite and initially default to zero. Calling spacing afterward replaces both values with the same gap, while calling grid_spacing afterward replaces them independently. The number of columns is supplied to grid(columns) at construction.

Configuration Example

use hera_kit::{grid, text, Alignment, ViewExt};

let extra = Some(text("Optional status"));
let content = grid(2)
    .alignment(Alignment::Leading)
    .spacing(8.0)
    .grid_spacing(20.0, 10.0)
    .child(text("Library"))
    .maybe_child(extra)
    .children(["Recent", "Saved"].into_iter().map(text))
    .padding(16.0);

The child order fills the grid row by row. The frame on an individual cell, rather than the grid’s alignment property, controls any additional alignment inside that cell.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/kit/src/view/primitives.rs
  • crates/kit/src/view/dsl.rs
  • crates/kit/src/layout/mod.rs
  • crates/kit/src/layout/validation.rs