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.
| Method | Purpose |
|---|---|
child | Appends one child view. |
maybe_child | Appends a child only when the option contains a view. |
children | Appends an iterator of views with one concrete item type. |
alignment | Configures child placement within the container. |
spacing | Sets the gap between adjacent children or tracks. |
child
fn child(self, child: impl View) -> SelfAppends 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>) -> SelfAppends 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>) -> SelfAppends 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) -> SelfSets 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) -> SelfSets 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.rscrates/kit/src/layout/mod.rscrates/kit/src/ag/reactive.rscrates/kit/src/view/dsl.rscrates/kit/src/layout/validation.rs