NEOLearn

Nodes and layout

Lay out UI with Node: sizes and Val units, flexbox direction, alignment and gaps, absolute positioning, display and visibility, z-order, UI scale and which camera UI draws on.

Updated October 20, 2026

On this page

Every UI element is an entity with a Node. A Node is a box: it says how big the box is, where it goes, how much space surrounds it and how its children are arranged. The engine computes the layout every frame, after your Update systems, so you change a node's fields and the screen follows.

A node with no Node parent is a root node and is laid out against the whole viewport. UI coordinates start at the top-left corner and grow right and down.

Sizes and units#

Lengths are Vals. Helper functions make them short to write:

HelperValMeaning
px(10)Val::Px(10.0)Logical pixels, multiplied by UiScale and the window's scale factor.
percent(50)Val::Percent(50.0)Percent of the parent: its width for widths, margins and padding, its height for heights.
vw(10), vh(10)Val::Vw, Val::VhPercent of the viewport's width or height.
vmin(10), vmax(10)Val::VMin, Val::VMaxPercent of the viewport's smaller or larger side.
em(2), rem(2)Val::Em, Val::RemMultiples of the node's font size, or the root font size.
auto()Val::AutoLet the layout decide.

UiRect holds four sides, for margin, padding and border. UiRect::all(px(8)), UiRect::axes(horizontal, vertical), UiRect::horizontal(v), UiRect::top(v) and so on build them, and px(8).all() is shorthand for UiRect::all(px(8)).

The fields you'll use most#

FieldWhat it does
width, height, min_*, max_*The box's size and limits.
aspect_ratioSome(width / height) keeps the box's shape.
margin, padding, borderSpace outside, inside and the border's thickness. Colour the border with BorderColor.
border_radiusRounded corners: BorderRadius::all(px(6)), BorderRadius::MAX for pills and circles.
displayDisplay::Flex (the default), Grid, Block or None (removed from layout).
position_typeRelative (the default) or Absolute.
left, right, top, bottomOffsets; with Absolute, the position inside the parent.
overflowWhat happens to children that don't fit; see Scrolling and overflow.

Flexbox#

By default a node lays its children out in a row, one after another. These fields control how:

FieldValuesWhat it does
flex_directionRow, Column, RowReverse, ColumnReverseThe main axis.
justify_contentStart, End, Center, SpaceBetween, SpaceAround, SpaceEvenly, ...Where children go along the main axis.
align_itemsStart, End, Center, Stretch, Baseline, ...Where children go across it.
align_selfas align_itemsOverrides align_items for one child.
flex_wrapNoWrap, Wrap, WrapReverseWhether children wrap onto new lines.
row_gap, column_gapa ValSpace between children.
flex_grow, flex_shrink, flex_basisnumbers, a ValHow children share leftover space.
A bottom bar with three evenly spaced slots
commands.spawn((
    Node {
        position_type: PositionType::Absolute,
        bottom: px(0),
        width: percent(100),
        height: px(80),
        flex_direction: FlexDirection::Row,
        justify_content: JustifyContent::SpaceEvenly,
        align_items: AlignItems::Center,
        ..default()
    },
    BackgroundColor(Color::srgba(0.0, 0.0, 0.0, 0.6)),
    children![slot(), slot(), slot()],
));

fn slot() -> impl Bundle {
    (
        Node { width: px(64), height: px(64), border: px(2).all(), border_radius: BorderRadius::all(px(8)), ..default() },
        BorderColor::all(Color::WHITE),
    )
}

Building the tree#

Nest nodes with children![...] when you spawn, or with with_children when you need a loop:

Rust
commands
    .spawn(Node { flex_direction: FlexDirection::Column, row_gap: px(8), ..default() })
    .with_children(|menu| {
        for label in ["Play", "Options", "Quit"] {
            menu.spawn(Text::new(label));
        }
    });

Hierarchy in general is covered in Relationships and hierarchy.

Absolute positioning and anchoring#

With position_type: PositionType::Absolute, a node is taken out of its parent's flow and placed by left, right, top and bottom. Use it for HUD corners, badges and overlays:

Rust
commands.spawn((
    Text::new("Score: 0"),
    Node { position_type: PositionType::Absolute, top: px(12), right: px(12), ..default() },
));

A node with FixedNode is positioned against the viewport even when it has a UI parent, and doesn't inherit its parent's clipping or transform. Use it for tooltips and pop-ups that belong to a widget but must escape its box.

Hiding nodes#

SetEffect
Node { display: Display::None, .. }Removed from layout: the space it took closes up. Its children are hidden too.
Visibility::HiddenNot drawn, but still takes up its space.

Draw order#

Siblings draw in the order they appear, later ones on top. ZIndex(n) changes the order among siblings. GlobalZIndex(n) lifts a node above (or below) everything else in the UI, whatever its parent, which is what modal dialogs need.

Transforms#

UI nodes don't use Transform. UiTransform moves, scales and rotates a node after layout, without disturbing its neighbours. Use it for animation: a button that grows on hover, a spinning icon.

Rust
UiTransform::from_rotation(Rot2::degrees(15.0))

UI scale#

The UiScale resource multiplies every pixel size in the UI. Set it from a settings menu to make the interface bigger or smaller: ui_scale.0 = 1.5;.

Which camera UI draws on#

Root nodes draw on the default UI camera: the camera with IsDefaultUiCamera, or else the highest-order camera that renders to the primary window. To put UI on another camera, such as one per split-screen player, add UiTargetCamera(camera_entity) to the root node. The UI is then laid out in that camera's viewport.

Examples#

ExampleWhat it shows
flex_layoutEvery combination of align_items and justify_content.
size_constraintsmin_* and max_*.
anchor_layoutPinning nodes to edges and corners.
fixed_nodeFixedNode.
display_and_visibilityDisplay::None against Visibility::Hidden. Needs --features neo_feathers.
z_indexZIndex and GlobalZIndex.
ui_transformUiTransform.
ui_scalingUiScale.
ui_target_cameraUiTargetCamera and camera order.

Run one from the engine core's workspace: cargo run --example flex_layout.

Next steps#