Documentation menu

Layout Fundamentals

Use parent proposals, intrinsic sizes, and wrapper modifiers to create interfaces that respond to available space.

Layout determines how a view uses the space offered by its parent and where its children appear within that space. Hera Kit performs this work in the application process, beginning with the surface dimensions and passing constraints down through the view hierarchy. As views report their sizes, their containers can determine child positions. Kit then sends the resolved geometry to the server as scene diffs.

Content and Containers

A view's content determines how it responds to a layout proposal. For text, Kit shapes the string with the selected font and measures the resulting lines, so the available width can affect both wrapping and height. An image instead has a natural size derived from its source dimensions. Rectangles, vector paths, and embedded surfaces have no comparable content measurement; they accept the finite space offered to them and need a deliberate size when that offer is unbounded.

Containers use those measurements to arrange their children. A horizontal or vertical stack places each child after the previous one, adding the configured spacing between them, while a grid aligns children in shared rows and columns. When content should overlap, a z_stack places its children within shared bounds. You can add a spacer to a horizontal or vertical stack when some of the available space should remain flexible.

Fill and Finite Proposals

A fill dimension expands to occupy the space offered by its parent, which means that the offer must have a finite bound. This becomes especially relevant inside a scroll container, where content receives an unbounded proposal along the scrolling axis. Give the scroll container a bounded viewport first; its content can then grow beyond that viewport without relying on fill to choose an arbitrary width or height.

Stacks allocate space from their children's measured sizes and any direct spacer children. Because the current implementation does not negotiate layout priorities, a constrained stack can still contain children whose combined fixed sizes exceed its bounds. Allow text to wrap, choose smaller explicit dimensions, or place long content in a scroll container as appropriate. Stacks also use physical cross-axis alignment rather than typographic baseline alignment.

Frame Wrappers

Use .frame(width, height) when content needs a specific surrounding region, such as a toolbar row or an icon slot. The modifier creates a wrapper that sizes and positions its content; it does not overwrite the content's own layout description. For a region that should respond more flexibly to its parent, frame_constraints(Frame) lets you configure each axis independently with minimum and maximum dimensions, fill behavior, and alignment.

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

let title = text("Library").frame_constraints(
    Frame::new()
        .fill_width()
        .min_height(44.0)
        .alignment(Alignment::Leading),
);

In this example, the frame fills the offered width, requests a minimum height of 44 logical pixels, and places the label at its leading edge. The parent's finite constraints still bound the result. Applying another frame would add a second surrounding region, so use modifier order to express the intended nesting.

Padding

Use padding when the layout needs to reserve space around content. Kit subtracts the insets from the proposal it passes to the child, then adds them back when calculating the wrapper's size. The insets must be finite and nonnegative. An offset serves a different purpose: it moves the visual result without changing how much space the parent reserves for it.

The same nesting determines which region receives a background. If you add padding before the background modifier, the background paints the padded bounds. If you add the background first, padding surrounds the already decorated content and remains unpainted. Reading the modifier chain from the content outward makes these differences easier to predict.

Layout Containers

Read the dedicated references for v_stack, h_stack, z_stack, grid, and spacer.

See layout internals for the attribute computations and validation behind these rules.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/kit/src/layout/mod.rs
  • crates/kit/src/view/geometry.rs
  • crates/kit/src/layout/validation.rs