Documentation menu

z_stack

Overlay child views within shared bounds and align them independently of their declaration sizes.

Use z_stack() -> ZStack to place several children within one shared layout region. This is useful for a badge over an illustration or an overlay within a component, where each child needs its own description but shares its placement with the others.

Overlay Construction

use hera_kit::{Alignment, Color, ViewExt, rectangle, text, z_stack};

let badge = z_stack()
    .alignment(Alignment::Center)
    .child(rectangle(Color::rgba(0.18, 0.25, 0.36, 1.0)).radius(12.0))
    .child(text("Ready").foreground(Color::rgba(1.0, 1.0, 1.0, 1.0)))
    .frame(160.0, 64.0);

The finite frame gives the rectangle a region to fill, while the text measures the size of its label. Center alignment then places the label within the same bounds. Centered placement is also the default for a z_stack.

Shared Bounds

The stack first measures its children under the parent's constraints to establish shared bounds. It then uses the chosen horizontal and vertical alignment factors to place each child within those bounds, allowing smaller children to align with an edge or sit in the center.

A child that fills a finite proposal can influence the stack's measured extent. If your goal is only to paint behind the size of some content, .background(paint) often expresses that relationship more directly, because the decoration adopts the resolved content bounds rather than contributing its own fill measurement.

Paint Order

Children overlay in declaration order when their effective ordering is equal; later content paints over earlier content. Renderer ordering still accounts for scene z-position, so backend code that changes z values must preserve the intended layering.

Overlaid content can also affect input. A visual overlay should use deliberate hit behavior when implemented at the backend layer so it does not unintentionally intercept the control beneath it.

Overlay Mechanisms

Choose the mechanism according to the relationship between the layers. A background decorates content's resolved bounds, whereas z_stack arranges independently described children together. If one of those children represents another application's retained UI, a surface_view supplies the surface embedding within that arrangement.

See modifiers and surface_view.

Component-Specific Reference

These methods configure the ZStack returned by z_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.

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 paint order when the children share the same effective scene ordering.

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

Places each child within the stack’s shared bounds using both horizontal and vertical alignment factors. Alignment::Center is the default; TopLeading, BottomTrailing, and the other edge and corner variants anchor smaller children accordingly. Alignment changes placement without changing the declaration order of overlapping children.

Configuration Example

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

let extra = Some(text("Optional status"));
let content = z_stack()
    .alignment(Alignment::Center)
    .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/mod.rs
  • crates/kit/src/layout/mod.rs
  • crates/kit/src/view/dsl.rs