/godot-ui

name: godot-ui
description: Use when building user interfaces — Control nodes, themes, anchors, containers, and layout patterns

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.

| Feature | `Node2D` | `Control` | |---|---|---| | Position model | World-space `position` (pixels from parent) | Anchor + offset relative to parent rect | | Size | No intrinsic size | Has `size`, `minimum_size`, `custom_minimum_size` | | Theme | None | Inherits and overrides `Theme` resources | | Focus | Not applicable | Built-in focus system (`focus_mode`, `grab_focus()`) | | Mouse events | Manual via `_input` | `gui_input`, `mouse_entered`, `mouse_exited` | | Layout helpers | None | `Container` subclasses auto-arrange children |

Control as Base Class

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

• `anchor_left`, `anchor_top`, `anchor_right`, `anchor_bottom` — fractional values (0.0–1.0) relative to the parent rect
• `offset_left`, `offset_top`, `offset_right`, `offset_bottom` — pixel offsets applied after the anchor resolves
• `size_flags_horizontal`, `size_flags_vertical` — 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.accessibility_live` changed type from `DisplayServer.AccessibilityLiveMode` to `AccessibilityServer.AccessibilityLiveMode` (`LIVE_OFF = 0` default, `LIVE_POLITE`, `LIVE_ASSERTIVE`) — 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](https://docs.godotengine.org/en/latest/tutorials/migrating/upgrading_to_godot_4.7.html).

---

2. Common Container Nodes

| Container | Purpose | When to Use | |---|---|---| | `VBoxContainer` | Stacks children vertically | Lists, option rows, vertical menus | | `HBoxContainer` | Stacks children horizontally | Toolbars, stat rows, horizontal nav | | `GridContainer` | Arranges children in a fixed-column grid | Inventory grids, key-binding tables | | `MarginContainer` | Adds padding around a single child | Wrapping any node to give it breathing room | | `PanelContainer` | Draws a `StyleBox` background, then lays out children | Card UI, dialog boxes, HUD panels | | `ScrollContainer` | Makes its single child scrollable; clips overflow | Long lists, logs, scrollable settings | | `TabContainer` | Stacks children as named tabs; shows one at a time | Settings screens, multi-section panels |

**Sizing tips:**

• Set `size_flags_horizontal = SIZE_EXPAND_FILL` on children that should fill available space.
• Use `custom_minimum_size` to prevent a child from collapsing to zero.
• `MarginContainer` reads margin from the theme property `margin_*`; override at runtime with `add_theme_constant_override("margin_left", 16)`.

> **Godot 4.7+:** `custom_maximum_size` (`Vector2(-1, -1)`) caps size per axis, prioritized over `custom_minimum_size`; `propagate_maximum_size` (default `false`) makes a parent's maximum constrain its Control children; `_get_maximum_size()` computes maximums from code.

> ⚠️ **Changed in Godot 4.7:** `TabContainer.all_tabs_in_front` is deprecated — it does nothing now, since tabs are always in front. Remove code that sets it. See [GH-118623](https://github.com/godotengine/godot/pull/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:

| Preset | Anchor values | Use case | |---|---|---| | Full Rect | L=0, T=0, R=1, B=1 | Overlay / fill parent — most common for root UI | | Center | L=0.5, T=0.5, R=0.5, B=0.5 | Fixed-size widget centred in parent | | Top Left | L=0, T=0, R=0, B=0 | Fixed-size widget pinned to top-left corner | | Top Right | L=1, T=0, R=1, B=0 | Fixed-size widget pinned to top-right corner | | Bottom Center | L=0.5, T=1, R=0.5, B=1 | HUD element anchored to bottom centre |

Setting Anchors in Code

Anchors resolve as `parent_size * anchor + offset` per edge, so setting them by hand means setting eight properties. `set_anchors_and_offsets_preset(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 `StyleBox`es. Apply at the root and let inheritance do the work; use `theme_override_*` only for one-off tweaks. `StyleBoxFlat` covers most flat-design needs (`bg_color`, `border_color`