v_stack
Arrange child views from top to bottom with explicit spacing and horizontal alignment.
Use v_stack() -> VStack to build a group whose children follow one another from top to bottom. You can add a fixed child with .child, supply repeated content through .children, or include optional content with .maybe_child. The stack measures those children together to determine the group's natural size.
Column Construction
use hera_kit::{Alignment, ViewExt, text, v_stack};
let heading = v_stack()
.alignment(Alignment::Leading)
.spacing(8.0)
.child(text("Library").ui_font(28.0))
.child(text("Your saved documents").ui_font(16.0))
.padding(24.0);Configure the stack before common modifiers such as padding, which return wrappers around the stack.
Measurement
A vertical stack's natural height includes each child's measured height and the gaps between adjacent children. Its natural width comes from the widest child, giving the group enough room to arrange the remaining children horizontally. The parent then constrains the stack's resolved size to the available region.
Ordinary children receive loosened parent constraints so they can measure their content. The stack does not negotiate layout priorities to compress them when their combined heights exceed the available space. For a long group, allow content to wrap or put the stack in a scroll viewport rather than relying on it to shrink fixed children automatically.
Child Alignment
Children narrower than the stack are placed according to the horizontal factor of .alignment. Choose Leading for the left edge, Center for the middle, or Trailing for the right edge. These names currently describe physical positions, so they do not reverse with the text's locale or writing direction.
The underlying stack defaults to top-leading layout alignment. Set alignment explicitly when the design depends on it.
Remaining Height Distribution
To use extra height within a bounded column, add a direct spacer() child. The stack gives each spacer a share of the height left after measuring ordinary content and spacing. This requires an available extent; an unbounded column does not give the spacer a screen-sized region to fill.
Read spacer, h_stack, and scrollable for related layouts.
Component-Specific Reference
These methods configure the VStack returned by v_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 horizontal placement of children within the column. Alignment::Leading, Center, and Trailing select its left edge, center, and right edge respectively; the horizontal factor of corner variants works the same way. The default is TopLeading. Alignment uses physical positions and does not reverse with paragraph direction.
spacing
fn spacing(self, spacing: f32) -> SelfSets the gap between adjacent children along the vertical 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::{v_stack, text, Alignment, ViewExt};
let extra = Some(text("Optional status"));
let content = v_stack()
.alignment(Alignment::Leading)
.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/view/dsl.rscrates/kit/src/layout/mod.rscrates/kit/src/layout/validation.rs