Godot UI / Control nodes (4.x)
Lay out responsive UI with Control anchors and Container nodes, style it with a
Theme, make it navigable by keyboard and gamepad, and prove the layout holds at more
than one screen size. Targets Godot 4.7 (see Version notes). Design rules (what a good
HUD or menu needs) live in game-ui-ux; load both for engine UI work.
When to use
- HUDs, menus, inventories, dialog boxes or settings screens built from
Controlnodes; UI that must adapt to window size; theming; focus navigation for controller/keyboard.
When not to use: in-world Node2D/sprites → godot-nodes-scenes; UI tweens →
godot-animation; rebinding → input-systems; card hands and VN text boxes →
card-game / visual-novel.
Core workflow
Read the stretch settings first.
project.godot[display]holdswindow/size/viewport_width/viewport_height(base size, default 1152x648),window/stretch/mode(canvas_itemsis the usual choice for UI-heavy games) andwindow/stretch/aspect(expandlets UI use extra width or height). Layout bugs on other screens usually start here.Use
Controlnodes for UI, notNode2D, and put HUDs under aCanvasLayerso the game camera does not move them.Anchor top-level panels; let Containers place their children. Outside containers, set anchors with presets (
set_anchors_and_offsets_preset()). Inside aVBoxContainer,HBoxContainer,GridContainerorMarginContainer, the container owns position and size; steer it withsize_flags_*. In a.tscn, a Full Rect panel reads:[node name="PauseMenu" type="Control"] anchors_preset = 15 anchor_right = 1.0 anchor_bottom = 1.0 grow_horizontal = 2 grow_vertical = 2Keep whatever
layout_modeline Godot wrote; it records whether anchors or a parent container drive the node.Style with one
Theme. Set a project-wide theme withgui/theme/custom="res://ui/theme.tres"inproject.godot, or assignthemeon the top Control; children inherit it. Use per-nodeadd_theme_*_overrideonly for exceptions.Wire focus. Give the first button focus when a menu opens (
grab_focus()), keepfocus_mode = FOCUS_ALLon anything a gamepad must reach, and setfocus_neighbor_*only where the automatic geometry guess is wrong.Connect signals (
pressed,toggled,text_submitted,value_changed).Check before you finish.
- Run the layout test (Pattern 4) headless:
godot --headless --path . --script res://tests/test_ui_layout.gdand read the exit code. It flags controls pushed off-screen and menus with nothing focused, at each size. - Run the
godot-nodes-scenesskill'sscripts/check_godot_project.py <project-dir>if you edited.tscn/.tresfiles (themes, StyleBoxes, fonts). - For a picture, on a machine with a GPU (not
--headless), capture frames and look at them:godot --path . --resolution 2560x1080 --write-movie $OUT/menu.png --quit-after 3 --scene res://ui/main_menu.tscnwrites numbered PNGs next to that path. Repeat at 1280x720. - With no Godot binary (
godot,godot4or$GODOT_BIN), ask the user to run these and paste the output or screenshots. Ask the user to try the menu with a gamepad and report any button that cannot be reached.
- Run the layout test (Pattern 4) headless:
Patterns
1. Full Rect from code (anchors and offsets)
extends Control
func _ready() -> void:
# Setting only anchors (or `anchors_preset`) keeps the old offsets, so the rect
# would not snap to the preset. This moves anchors AND resets offsets.
set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)2. A menu from containers, with initial focus
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. One child takes the leftover space
func _ready() -> void:
$Label.size_flags_horizontal = Control.SIZE_SHRINK_BEGIN
$Spacer.size_flags_horizontal = Control.SIZE_EXPAND_FILL # grows to fill4. Headless layout test at several sizes
# res://tests/test_ui_layout.gd
extends SceneTree
# The sizes the UI really gets. With stretch mode canvas_items and aspect "expand",
# a 2560x1080 window on a 1152x648 base gives the UI 1536x648, not 2560x1080.
const SIZES: Array[Vector2i] = [Vector2i(1152, 648), Vector2i(1536, 648), Vector2i(1152, 864)]
func _initialize() -> void:
var failed := 0
for size in SIZES:
var vp := SubViewport.new()
vp.size = size
root.add_child(vp)
var ui: Control = load("res://ui/main_menu.tscn").instantiate()
vp.add_child(ui)
await process_frame
await process_frame # containers re-sort a frame later
var screen := Rect2(Vector2.ZERO, Vector2(size))
for node in ui.find_children("*", "Control", true, false):
var c := node as Control
if c.is_visible_in_tree() and not screen.encloses(c.get_global_rect()):
failed += 1
push_error("%s off-screen at %s: %s" % [ui.get_path_to(c), size, c.get_global_rect()])
if vp.gui_get_focus_owner() == null:
failed += 1
push_error("nothing has focus at %s, so a gamepad cannot navigate" % size)
vp.free()
print("Results: %d failed" % failed)
quit(1 if failed > 0 else 0)Children of a ScrollContainer are meant to extend past it; skip them (or check only the
container) when the menu scrolls.
Gotchas
- Mixing manual position with Containers. A container child cannot keep its own
position or anchors; the container overwrites them on every sort. To nudge, rotate or
scale one (a hover pop), set
offset_transform_enabled = trueand useoffset_transform_position/_rotation/_scale, which the container leaves alone. - Anchors vs offsets. Anchors are fractions of the parent; offsets are pixels from the anchored point. Positioning with anchors at 0 makes UI ignore window size.
- UI under a
Node2Ddoesn't theme, anchor or take focus correctly. Keep UI in aControlsubtree, under aCanvasLayerfor HUDs. - Gamepad does nothing → nothing has focus. Call
grab_focus()when the screen opens; plainControls default toFOCUS_NONE,FOCUS_CLICKis mouse-only, andgrab_focus()on aFOCUS_NONEcontrol only prints a warning. - Invisible full-rect panel swallows clicks → its
mouse_filterisSTOP. SetMOUSE_FILTER_IGNOREon decorative panels and HUD roots. - Looks right in the editor, cramped or off-screen on ultrawide or 4:3 → stretch
aspectiskeep(black bars) or the panel is anchored to a corner instead of the edge it should follow. Test the sizes the UI actually gets (Pattern 4). - Theme vs override. Per-node
add_theme_*_overridecalls beat the inheritedTheme; many of them defeat central theming and make restyling slow. rect_*properties are renamed. Godot 3'srect_size/rect_position/rect_min_sizeare nowsize/position/custom_minimum_size.
References
- Read
references/layout-and-theming.mdwhen you need the anchor/offset maths, every Container type, size-flag values, building a Theme and StyleBox in code, focus neighbour wiring, offset transforms, the built-inVirtualJoystick, or common Control signals.
Related skills
game-ui-uxfor engine-neutral rules: scaling, safe areas, focus flow, screen stack.godot-animationfor Tween-based UI transitions.godot-signals-groupsfor wiring UI events to game logic.input-systemsfor rebindable input and multi-device focus.card-game/visual-novelfor UI-heavy genre templates.
Version notes
Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).
Control.offset_transform_*and theVirtualJoysticknode are new in 4.7.- Default base size is 1152x648 and default stretch mode is
disabled, aspectkeep. --write-moviewith a.pngpath writes an image sequence;--resolutionrequests the window size.
Sources: Control @ 4.7.2-stable, ProjectSettings @ 4.7.2-stable, main.cpp @ 4.7.2-stable, Multiple resolutions, Godot 4.7 release.