Documentation menu

h_stack

Arrange child views from left to right with spacing, vertical alignment, and optional flexible gaps.

Use h_stack() -> HStack when related views should read as a row, such as a toolbar, a labeled value, or a compact status group. The container places children from left to right and uses their measurements to determine the row's natural size.

Row Construction

use hera_kit::{Alignment, ViewExt, h_stack, spacer, text};

let row = h_stack()
    .alignment(Alignment::Center)
    .spacing(12.0)
    .child(text("Downloads"))
    .child(spacer())
    .child(text("3 items"))
    .frame(360.0, 48.0);

In this example, the frame supplies a finite width wider than the two labels, leaving room for the spacer between them. The spacer consumes that remainder and separates the count from the title. Without extra offered width, the row would remain close to its content's measured width.

Measurement

The row measures its natural width by adding the children's widths and the spacing between them, while its natural height comes from the tallest child. Its parent then constrains the container to the available bounds. This lets a row size around content without assigning every child an equal-width column.

Ordinary children measure under loosened parent constraints, so they can retain their own intrinsic widths. If several rows need their columns to line up, use grid to establish shared tracks. Explicit frames are also available when a design requires particular widths.

Vertical Alignment

The vertical factor of Alignment determines where shorter children sit within the row. Choose Top, Center, or Bottom to express that placement. These options align bounds rather than text baselines, so rows with different font sizes may need a deliberate visual alignment choice.

For example, centering a small label beside a large value centers their measured regions; it does not align the characters' baselines. Typographic baseline alignment is not currently part of stack layout.

Identity During Reordering

Use .key(stable_id) on repeated stateful children whose order can change. A label's text is not automatically its identity, and a list index will not preserve item state when items move.

See spacer for flexible allocation and identity for mounted storage behavior.

Component-Specific Reference

These methods configure the HStack returned by h_stack(). 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.
alignmentConfigures child placement within the container.
spacingSets the gap between adjacent children or tracks.

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

Sets the vertical placement of children within the row. Alignment::Top, Center, and Bottom align their measured bounds at the corresponding position; corner variants use the same vertical factors. The default is TopLeading. These are bounds-based alignments rather than typographic baseline alignments.

spacing

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

Sets the gap between adjacent children along the horizontal axis. 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.

Configuration Example

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

let extra = Some(text("Optional status"));
let content = h_stack()
    .alignment(Alignment::Center)
    .spacing(8.0)
    .child(text("Library"))
    .maybe_child(extra)
    .children(["Recent", "Saved"].into_iter().map(text))
    .padding(16.0);

The builder methods run before padding, which returns a common modifier wrapper. See View Modifiers for the methods available on that wrapper.

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/layout/mod.rs
  • crates/kit/src/ag/reactive.rs
  • crates/kit/src/view/dsl.rs
  • crates/kit/src/layout/validation.rs