bevy_ui

Bevy's UI system. Flexbox layout via taffy, an entity-based scene graph for UI nodes, focus integration, and the data structures the UI renderer consumes.

Purpose

bevy_ui provides:

• Node — the UI element component, with size and layout props.
• Style-like components — BorderColor, BackgroundColor, Outline, BorderRadius, etc., split into many small components instead of one mega-struct.
• Layout — flexbox via taffy, plus grid layout primitives.
• Z-order — ZIndex plus the implicit child-order stacking.
• Picking integration — UI picking backend.
• Focus integration — keyboard navigation hooks.
• Camera attachment — UiTargetCamera controls which camera renders a UI tree.

Directory layout

crates/bevy_ui/src/
├── lib.rs            # UiPlugin
├── ui_node.rs        # Node + style components (3,200 lines, central file)
├── layout/           # taffy integration: building the layout tree, applying results
├── focus.rs          # Focus traversal hooks
├── geometry.rs       # Val, Val2, Rect helpers
├── update.rs         # Per-frame update systems
├── picking_backend.rs # UI picking backend
├── stack.rs          # Z-order computation
├── widget/           # Widgets (button, label, image)
├── ui_transform.rs   # UiTransform + propagation
└── …

Key abstractions

Type	File	Description
Node	crates/bevy_ui/src/ui_node.rs	The UI element component.
BackgroundColor, BorderColor, BorderRadius, Outline	crates/bevy_ui/src/ui_node.rs	Visual style components.
Val, Val2	crates/bevy_ui/src/geometry.rs	Length type with px/percent/auto.
UiPlugin, UiPluginGroup	crates/bevy_ui/src/lib.rs	Plugin entry points.
UiSystem	crates/bevy_ui/src/lib.rs	System set ordering for UI passes.
UiTargetCamera	crates/bevy_ui/src/lib.rs	Component pointing a UI tree at a specific camera.
ZIndex	crates/bevy_ui/src/stack.rs	Per-node Z-order.

How it works

graph LR
    A[user spawns Node hierarchy] --> B[ui layout: build taffy tree]
    B --> C[taffy::compute_layout]
    C --> D[apply layout: write back ComputedNode/Transform]
    D --> E[UiPickingBackend uses Computed rectangles]
    D --> F[bevy_ui_render extracts UI nodes]

Each frame in PostUpdate:

1. Build a taffy tree mirroring the entity hierarchy. Update entries when ECS structure changes.
2. Compute layout per root.
3. Write computed sizes/positions back to ComputedNode and Transform on each entity.
4. The renderer extracts the laid-out tree.

Integration points

• Depends on: taffy, bevy_app, bevy_ecs, bevy_math, bevy_color, bevy_image, bevy_text, bevy_input, bevy_input_focus, bevy_picking, bevy_camera, bevy_transform, bevy_window.
• Depended on by: bevy_ui_render, bevy_ui_widgets, bevy_feathers.

Entry points for modification

• New layout property: ui_node.rs for the component, layout/ to teach taffy about it.
• New visual style component: add to ui_node.rs. Update extraction in bevy_ui_render.
• New picking semantics: picking_backend.rs.
• Performance: update.rs and layout/. The taffy tree mirror is one of the heavier per-frame ECS workloads.

See also

• bevy_ui_render — renders the layout output.
• bevy_ui_widgets — primitive widgets.
• bevy_feathers — themed widget set.
• UI feature page.