Godot UI — Control Nodes, Themes & Layout

All examples target Godot 4.3+ with no deprecated APIs; GDScript first, then C#.

Related skills: responsive-ui for multi-resolution scaling, hud-system for in-game HUD patterns, dialogue-system for dialogue UI presentation, tween-animation for UI transition and animation effects.

1. Control Node Hierarchy

How Control Differs from Node2D

Control is the base class for all UI nodes — it lives in a separate scene-tree branch from Node2D/Node3D with a fundamentally different layout model.

Control as Base Class

Every UI widget (Button, Label, LineEdit, etc.) extends Control. Key properties defined on Control itself:

• anchorleft, anchortop, anchorright, anchorbottom — fractional values (0.0–1.0) relative to the parent rect
• offsetleft, offsettop, offsetright, offsetbottom — pixel offsets applied after the anchor resolves
• sizeflagshorizontal, sizeflagsvertical — how the node participates in Container layout
• theme — a Theme resource; if null, walks up the tree to the nearest ancestor with one
• focus_mode — whether the node can receive keyboard/gamepad focus

Place UI nodes inside a CanvasLayer (or directly under the scene root's built-in canvas) so they render on top of the 3D/2D world, unaffected by Camera transforms.

⚠️ Changed in Godot 4.7: Control.accessibilitylive changed type from DisplayServer.AccessibilityLiveMode to AccessibilityServer.AccessibilityLiveMode (LIVEOFF = 0 default, LIVEPOLITE, LIVEASSERTIVE) — accessibility enums/APIs moved to the new AccessibilityServer singleton. GDScript-compatible; breaks C# binary/source compatibility (rebuild against the new enum). See the 4.7 migration guide.

2. Common Container Nodes

Sizing tips:

• Set sizeflagshorizontal = SIZEEXPANDFILL on children that should fill available space.
• Use customminimumsize to prevent a child from collapsing to zero.
• MarginContainer reads margin from the theme property margin*; override at runtime with addthemeconstantoverride("margin_left", 16).

Godot 4.7+: custommaximumsize (Vector2(-1, -1)) caps size per axis, prioritized over customminimumsize; propagatemaximumsize (default false) makes a parent's maximum constrain its Control children; getmaximum_size() computes maximums from code.

⚠️ Changed in Godot 4.7: TabContainer.alltabsin_front is deprecated — it does nothing now, since tabs are always in front. Remove code that sets it. See GH-118623.

3. Anchors & Margins

How Anchor Presets Work

An anchor is a point on the parent rect expressed as a fraction (0 = top/left edge, 1 = bottom/right edge). Godot resolves the final pixel position of each edge as:

final_left   = parent_width  * anchor_left   + offset_left
final_top    = parent_height * anchor_top    + offset_top
final_right  = parent_width  * anchor_right  + offset_right
final_bottom = parent_height * anchor_bottom + offset_bottom

The editor exposes built-in presets:

Setting Anchors in Code

Anchors resolve as parentsize anchor + offset per edge, so setting them by hand means setting eight properties. setanchorsandoffsetspreset(Control.PRESET) does it in one call — use that, then adjust offset_* for margins (negative on right/bottom).

The anchor-vs-offset rule (keep offsets at 0 and let anchors do the work) plus full GDScript + C# examples — full-rect fill, top-right HUD with 16 px margins, and a custom half-screen side panel: [references/anchors-in-code.md](references/anchors-in-code.md)

4. Theme System

A Theme resource centralizes fonts, colors, and StyleBoxes. Apply at the root and let inheritance do the work; use themeoverride* only for one-off tweaks. StyleBoxFlat covers most flat-design needs (bgcolor, bordercolor, cornerradius, borderwidth); StyleBoxTexture for textures.

See [references/theme-system.md](references/theme-system.md) for the full Theme resource creation walk-through, StyleBoxFlat properties, font overrides, theme inheritance rules, and per-node themeoverride* methods.

Godot 4.7+: GradientTexture2D's Fill enum gains FILL_CONIC — colors interpolated in a cone (angular) pattern; radial progress/cooldown indicators without a shader (C#: FillEnum.Conic).

5. Focus & Navigation

Focus modes (FOCUSNONE, FOCUSCLICK, FOCUSALL) gate keyboard/gamepad navigation. Wire chains with focusneighbortop / bottom / left / right, or rely on automatic spatial detection. Call grab_focus() on the first interactive element when a menu opens.

See [references/focus-and-navigation.md](references/focus-and-navigation.md) for focus mode details, focusneighbor chain examples, gamepad/keyboard input handling, and grabfocus patterns.

6. Common UI Patterns

Three canonical scenes: a main menu (centered VBoxContainer with title + button list), a settings screen with tabs (TabContainer + child panels per category), and a pause menu overlay (full-rect ColorRect background + centered options panel, paused via get_tree().paused = true).

See [references/ui-patterns.md](references/ui-patterns.md) for the full scene-tree fragments and GDScript wiring for each pattern.

Godot 4.7+: offsettransform* — visual-only UI-juice transform (shake/pulse) that never re-triggers container layout; getcursorshape(atposition) — per-position cursor shapes; PopupMenu search bar (searchbarenabled, fuzzy by default) plus setitemindex() for reordering; TextureRect STRETCH_TILE now tiles AtlasTextures (only non-zero margin unsupported). Code: [references/ui-patterns.md](references/ui-patterns.md#godot-47-additions).

⚠️ Changed in Godot 4.7: RichTextLabel.addimage() / updateimage() sizing was reworked — width/height are now float; widthinpercent/heightinpercent bools become widthunit/heightunit, taking the new ImageUnit enum (IMAGEUNITPIXEL, IMAGEUNITPERCENT, IMAGEUNITEM — em scales with font size). ImageUpdateMask.UPDATEWIDTHINPERCENT is renamed UPDATEWIDTHUNIT, breaking GDScript using the old name. See the 4.7 migration guide.

# Configure via Theme Overrides → Constants in the inspector, or add_theme_* overrides at runtime.
func apply_stacked_outlines(label: Label) -> void:
    # Outer outline — wide, dark
    label.add_theme_constant_override("outline_size", 6)
    label.add_theme_color_override("font_outline_color", Color(0.0, 0.0, 0.0, 0.9))

    # Shadow (second layered effect)
    label.add_theme_constant_override("shadow_offset_x", 2)
    label.add_theme_constant_override("shadow_offset_y", 2)
    label.add_theme_color_override("font_shadow_color", Color(0.0, 0.0, 0.0, 0.5))

public void ApplyStackedOutlines(Label label)
{
    // Outer outline — wide, dark
    label.AddThemeConstantOverride("outline_size", 6);
    label.AddThemeColorOverride("font_outline_color", new Color(0f, 0f, 0f, 0.9f));

    // Shadow (second layered effect)
    label.AddThemeConstantOverride("shadow_offset_x", 2);
    label.AddThemeConstantOverride("shadow_offset_y", 2);
    label.AddThemeColorOverride("font_shadow_color", new Color(0f, 0f, 0f, 0.5f));
}

# Multiple outline-style effects via BBCode + theme
$RichTextLabel.text = "[outline size=4 color=#000000]Level Up![/outline]"
# Additional layers via theme overrides, as above.