Skip to main content

ZStack

ZStack is the layered layout primitive.

It paints children in order from back to front: the first child is at the bottom and the last child is on top. This makes it the right tool for layered cards, image-plus-badge compositions, full-screen overlays, floating controls, and other interfaces where depth matters.

Use ZStack when layering is the real structural idea. Do not use it as a replacement for ordinary rows and columns. If the relationship between children is really sequential rather than layered, a stack on the z axis will make the code harder to understand.

Example​

use fission::core::ui::{Positioned, Text, ZStack};

let node = ZStack {
    children: vec![
        Text::new("Base layer").into_node(),
        Positioned {
            bottom: Some(8.0),
            right: Some(8.0),
            child: Some(Box::new(Text::new("Badge").into_node())),
            ..Default::default()
        }
        .into_node(),
    ],
    ..Default::default()
}
.into_node();

Field table​

FieldTypeMeaningNotes / default behavior
idOption<NodeId>Stable node identity.Defaults to None.
childrenVec<Node>Layered children, painted in order.Defaults to an empty list. First child is bottom, last child is top.

Layout behavior​

ZStack sizes itself from its non-absolute children and then lays those children into the same bounds. Children wrapped in Positioned or absolute_fill(...) are treated specially by the layout engine as absolute children relative to the stack's bounds.

This is what makes ZStack the natural parent for corner badges, floating overlays, and full-surface scrims.

Specific advice​

If you only need exactly two layers with a simple "main content plus top layer" relationship, Overlay is often easier to read. Use ZStack when you really need the general layered layout model.

Overlay, Positioned, and absolute_fill(...).