Documentation menu

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.

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 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) -> Self

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