Godot UI / Control nodes (4.x)
Lay out responsive UI with Control anchors and Container nodes, style it with a
Theme, and make it navigable by keyboard and gamepad. Targets Godot 4.7.
When to use
- Use when building HUDs, menus, inventories, dialog boxes, or settings screens with
Control-derived nodes; arranging UI that adapts to window size; theming; or wiring
focus navigation for controller/keyboard.
When not to use: in-world 2D nodes (Node2D/sprites) → godot-nodes-scenes;
animating UI transitions → godot-animation (Tween); genre UIs like card hands →
card-game/visual-novel. For full input rebinding → input-systems.
Core workflow
- Use
Control nodes for UI, not Node2D. Controls have a rect (position + size),
anchors, and participate in focus/theming.
- Anchor for responsiveness. Anchors are fractions (0–1) of the parent rect that the
Control's edges stick to. Use the editor's Layout presets (Top-Left, Full Rect,
Center, etc.) instead of hand-placing pixels.
- Let Containers position children. Put children in a
VBoxContainer,
HBoxContainer, GridContainer, MarginContainer, etc. — the container sets their
position/size; you control flow with size_flags. Don't set child anchors inside a
container (it overrides them).
- Style with a
Theme. Assign a Theme resource on a top Control; children inherit
it. Override per-node with theme overrides only when necessary.
- Wire focus so gamepad/keyboard can move between buttons; set a default focused
control and define neighbors or rely on auto-neighbor.
- Connect signals (
pressed, toggled, text_submitted, value_changed).
Patterns
1. Responsive layout with anchors (code form)
extends Control
func _ready() -> void:
# Stretch this panel to fill its parent (the editor's "Full Rect" preset).
# Setting only anchors (or `anchors_preset`) keeps the current offsets, so the
# control keeps its old rect; this call moves anchors AND resets offsets.
set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
# Manual equivalent: anchor_left = 0; anchor_top = 0; anchor_right = 1;
# anchor_bottom = 1, then set all four offset_* to 0.
2. A menu built from containers + button signals
extends VBoxContainer # children stack vertically, auto-sized
func _ready() -> void:
for child in get_children():
if child is Button:
child.pressed.connect(_on_button_pressed.bind(child.name))
# Give the first button focus so a gamepad can navigate immediately.
if get_child_count() > 0:
(get_child(0) as Control).grab_focus()
func _on_button_pressed(which: StringName) -> void:
match which:
"PlayButton": get_tree().change_scene_to_file("res://game.tscn")
"QuitButton": get_tree().quit()
3. Size flags: make one child expand to fill leftover space
# In a HBoxContainer: a label on the left, a spacer that eats remaining width.
func _ready() -> void:
$Label.size_flags_horizontal = Control.SIZE_SHRINK_BEGIN
$Spacer.size_flags_horizontal = Control.SIZE_EXPAND_FILL # grows to fill
4. Theme override for one node (without a full Theme resource)
func _ready() -> void:
# Per-node overrides: use add_theme_* (type-specific setters).
$Title.add_theme_font_size_override("font_size", 32)
$Title.add_theme_color_override("font_color", Color.GOLD)
$Panel.add_theme_stylebox_override("panel", preload("res://ui/panel.stylebox.tres"))
Pitfalls
- Mixing manual position with Containers. A child of a
Container cannot set its own
position/anchors — the container owns layout. To free-place, take the node out of the
container or use a plain Control/PanelContainer wrapper. To nudge, rotate or scale a
container child (e.g. a hover pop) in 4.7+, set offset_transform_enabled = true and use
offset_transform_position/_rotation/_scale; the container leaves those alone.
- Anchors vs offsets. Anchors are fractions of the parent; offsets are pixel deltas
from the anchored point. Set anchors via presets, then nudge with offsets. Setting only
position while anchors are at 0 makes UI not scale with the window.
Node2D for UI. Buttons/labels parented under a Node2D won't theme or take focus
correctly. Keep UI under a CanvasLayer/Control subtree.
- Focus lost on gamepad. If nothing is focused, directional input does nothing. Call
grab_focus() on an initial control and ensure focus_mode is FOCUS_ALL (FOCUS_CLICK
is mouse-only, FOCUS_NONE never focuses).
- Theme vs theme override. A
Theme resource styles a whole subtree; add_theme_*
overrides one node. Overusing per-node overrides defeats centralized theming.
rect_* properties are renamed. Godot 3's rect_size/rect_position/rect_min_size
are now size/position/custom_minimum_size in 4.x.
mouse_filter on a full-rect Control can swallow clicks meant for nodes beneath it;
set MOUSE_FILTER_IGNORE on purely decorative panels.
References
- For the anchor/offset math, every Container type, building/extending Theme and StyleBox
resources, focus neighbor wiring, and
CanvasLayer for HUDs, read
references/layout-and-theming.md.
Related skills
game-ui-ux — cross-engine UI/UX: responsive scaling, safe areas, focus navigation, screen flow.
godot-animation — Tween-based UI transitions and juicing.
godot-signals-groups — connecting UI events to game logic.
input-systems — rebindable input and multi-device focus.
card-game / visual-novel — UI-heavy genre templates.
1---2name: godot-ui-control3description: >4 Build Godot 4.7 user interfaces with Control nodes: anchors and offsets for5 responsive layout, Container nodes (VBox/HBox/Grid/Margin) for automatic6 arrangement, Theme resources for consistent styling, and keyboard/gamepad focus7 navigation. Use when laying out a HUD, menu, or UI in a Godot project, working8 with Control/Container nodes, anchors, themes, or focus in a .tscn.9metadata:10 source: https://skillmd.com/skills/junmystery/godot-ui-control11---1213# Godot UI / Control nodes (4.x)1415Lay out responsive UI with `Control` anchors and `Container` nodes, style it with a16`Theme`, and make it navigable by keyboard and gamepad. Targets **Godot 4.7**.1718## When to use1920- Use when building HUDs, menus, inventories, dialog boxes, or settings screens with21 `Control`-derived nodes; arranging UI that adapts to window size; theming; or wiring22 focus navigation for controller/keyboard.2324**When *not* to use:** in-world 2D nodes (`Node2D`/sprites) → `godot-nodes-scenes`;25animating UI transitions → `godot-animation` (Tween); genre UIs like card hands →26`card-game`/`visual-novel`. For full input rebinding → `input-systems`.2728## Core workflow29301. **Use `Control` nodes for UI**, not `Node2D`. Controls have a rect (position + size),31 anchors, and participate in focus/theming.322. **Anchor for responsiveness.** Anchors are fractions (0–1) of the parent rect that the33 Control's edges stick to. Use the editor's **Layout** presets (Top-Left, Full Rect,34 Center, etc.) instead of hand-placing pixels.353. **Let Containers position children.** Put children in a `VBoxContainer`,36 `HBoxContainer`, `GridContainer`, `MarginContainer`, etc. — the container sets their37 position/size; you control flow with `size_flags`. Don't set child anchors inside a38 container (it overrides them).394. **Style with a `Theme`.** Assign a `Theme` resource on a top Control; children inherit40 it. Override per-node with theme overrides only when necessary.415. **Wire focus** so gamepad/keyboard can move between buttons; set a default focused42 control and define neighbors or rely on auto-neighbor.436. **Connect signals** (`pressed`, `toggled`, `text_submitted`, `value_changed`).4445## Patterns4647### 1. Responsive layout with anchors (code form)4849```gdscript50extends Control5152func _ready() -> void:53 # Stretch this panel to fill its parent (the editor's "Full Rect" preset).54 # Setting only anchors (or `anchors_preset`) keeps the current offsets, so the55 # control keeps its old rect; this call moves anchors AND resets offsets.56 set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)57 # Manual equivalent: anchor_left = 0; anchor_top = 0; anchor_right = 1;58 # anchor_bottom = 1, then set all four offset_* to 0.59```6061### 2. A menu built from containers + button signals6263```gdscript64extends VBoxContainer # children stack vertically, auto-sized6566func _ready() -> void:67 for child in get_children():68 if child is Button:69 child.pressed.connect(_on_button_pressed.bind(child.name))70 # Give the first button focus so a gamepad can navigate immediately.71 if get_child_count() > 0:72 (get_child(0) as Control).grab_focus()7374func _on_button_pressed(which: StringName) -> void:75 match which:76 "PlayButton": get_tree().change_scene_to_file("res://game.tscn")77 "QuitButton": get_tree().quit()78```7980### 3. Size flags: make one child expand to fill leftover space8182```gdscript83# In a HBoxContainer: a label on the left, a spacer that eats remaining width.84func _ready() -> void:85 $Label.size_flags_horizontal = Control.SIZE_SHRINK_BEGIN86 $Spacer.size_flags_horizontal = Control.SIZE_EXPAND_FILL # grows to fill87```8889### 4. Theme override for one node (without a full Theme resource)9091```gdscript92func _ready() -> void:93 # Per-node overrides: use add_theme_* (type-specific setters).94 $Title.add_theme_font_size_override("font_size", 32)95 $Title.add_theme_color_override("font_color", Color.GOLD)96 $Panel.add_theme_stylebox_override("panel", preload("res://ui/panel.stylebox.tres"))97```9899## Pitfalls100101- **Mixing manual position with Containers.** A child of a `Container` cannot set its own102 position/anchors — the container owns layout. To free-place, take the node out of the103 container or use a plain `Control`/`PanelContainer` wrapper. To nudge, rotate or scale a104 container child (e.g. a hover pop) in 4.7+, set `offset_transform_enabled = true` and use105 `offset_transform_position`/`_rotation`/`_scale`; the container leaves those alone.106- **Anchors vs offsets.** Anchors are fractions of the parent; offsets are pixel deltas107 from the anchored point. Set anchors via presets, then nudge with offsets. Setting only108 position while anchors are at 0 makes UI not scale with the window.109- **`Node2D` for UI.** Buttons/labels parented under a `Node2D` won't theme or take focus110 correctly. Keep UI under a `CanvasLayer`/`Control` subtree.111- **Focus lost on gamepad.** If nothing is focused, directional input does nothing. Call112 `grab_focus()` on an initial control and ensure `focus_mode` is `FOCUS_ALL` (`FOCUS_CLICK`113 is mouse-only, `FOCUS_NONE` never focuses).114- **Theme vs theme override.** A `Theme` resource styles a whole subtree; `add_theme_*`115 overrides one node. Overusing per-node overrides defeats centralized theming.116- **`rect_*` properties are renamed.** Godot 3's `rect_size`/`rect_position`/`rect_min_size`117 are now `size`/`position`/`custom_minimum_size` in 4.x.118- **`mouse_filter`** on a full-rect Control can swallow clicks meant for nodes beneath it;119 set `MOUSE_FILTER_IGNORE` on purely decorative panels.120121## References122123- For the anchor/offset math, every Container type, building/extending Theme and StyleBox124 resources, focus neighbor wiring, and `CanvasLayer` for HUDs, read125 `references/layout-and-theming.md`.126127## Related skills128129- `game-ui-ux` — cross-engine UI/UX: responsive scaling, safe areas, focus navigation, screen flow.130- `godot-animation` — Tween-based UI transitions and juicing.131- `godot-signals-groups` — connecting UI events to game logic.132- `input-systems` — rebindable input and multi-device focus.133- `card-game` / `visual-novel` — UI-heavy genre templates.