Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 36 ยท UI, Audio and Animation

Themes and Responsive UI

Style a Godot 4 interface with Theme resources: StyleBoxFlat, fonts, theme type variations, per-control overrides, content scale and stretch modes, safe areas and localization hints, with stand-ins.

A game UI needs one consistent look and a layout that survives different screens. Godot's answer is the Theme resource: one place that defines colors, fonts, spacing and the look of every control type. This lesson shows how themes cascade, how to build styles, and how to make a UI scale from a phone to a 4K monitor.

Godot cannot run on this site, so the engine settings and code are read-only; the runnable blocks are Python stand-ins for the lookup and scaling rules. Before this lesson read Control nodes and containers.

What a Theme contains

A Theme holds items grouped by control type (Button, Label, Panel, ...), each with five kinds of items:

  • Colors (font_color, font_hover_color)
  • Constants (integers such as separation, margin_left)
  • Fonts and font sizes
  • Icons
  • Styleboxes: how a background is drawn (normal, hover, pressed, disabled, focus for a Button)

Create one by right-clicking the FileSystem dock: New Resource > Theme, double-click it to open the Theme editor at the bottom, and use Add Type to start with the controls you use. Save it as res://ui/main_theme.tres.

Styleboxes

The most used stylebox is StyleBoxFlat: a rectangle with a background color, border, rounded corners, padding (content margins) and optional shadow. StyleBoxTexture uses a 9-patch image that stretches the middle but keeps the corners crisp, and StyleBoxEmpty draws nothing, which is how you remove the default focus outline.

GDSCRIPT
func make_button_style(color: Color) -> StyleBoxFlat:
	var box := StyleBoxFlat.new()
	box.bg_color = color
	box.set_corner_radius_all(10)
	box.set_content_margin_all(12)
	box.border_width_bottom = 4
	box.border_color = color.darkened(0.35)
	return box

func _ready() -> void:
	var theme := Theme.new()
	theme.set_stylebox("normal", "Button", make_button_style(Color("#3b82f6")))
	theme.set_stylebox("hover", "Button", make_button_style(Color("#60a5fa")))
	theme.set_stylebox("pressed", "Button", make_button_style(Color("#1d4ed8")))
	theme.set_color("font_color", "Button", Color.WHITE)
	theme.set_font_size("font_size", "Button", 22)
	$Menu.theme = theme

How a theme is looked up

A control searches for each item in this order, using the first one found: its own local override (add_theme_color_override("font_color", ...)), then the theme property on the control, then the theme of each ancestor control going up the tree, then the project theme (Project Settings > GUI > Theme > Custom), and finally Godot's built-in default theme. Set a theme on your menu's root control and every child inherits it.

Python Stand-in (Python, not Godot): theme lookup walks up the tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Overrides are for exceptions. If you override many controls, create a theme type variation instead: in the Theme editor add a type that has a base type (for example DangerButton based on Button), then set theme_type_variation = "DangerButton" on the controls that need it. The variation carries the whole look without per-node code.

Fonts

Import a .ttf or .otf file and Godot makes a FontFile. Set a default font and default font size on the theme. Use FontVariation for bold or italic synthesized from a base font, and a fallback font for characters your main font lacks (CJK, emoji). Turn on MSDF rendering in the font import settings to keep text sharp at any scale. RichTextLabel supports BBCode such as [b], [color=red] and [wave] for effects.

Scaling for different screens

Set these in Project Settings > Display > Window:

  • Viewport Width/Height: the size you design for, for example 1280 by 720.
  • Stretch > Mode: canvas_items redraws 2D and UI at the real resolution (sharp text); viewport renders at the design size and scales the image (right for pixel art); disabled leaves everything in real pixels.
  • Stretch > Aspect: keep adds black bars, expand shows extra space (your UI must use anchors to use it), keep_width or keep_height fix one axis.
  • Scale mode: integer scaling for crisp pixels.
Python Stand-in (Python, not Godot): scale factor and black bars for the keep aspect

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A 21:9 window (2560 by 1080) gets vertical bars (left and right) with the keep aspect; a portrait phone gets horizontal bars at top and bottom. With expand, anchored controls use that space instead.

Safe areas and accessibility

Phones have notches and rounded corners: query DisplayServer.get_display_safe_area() and add margins to the root MarginContainer. Offer a UI scale slider that sets get_window().content_scale_factor, keep text at least 16 to 18 pixels at design size, never rely on color alone, and test with the Localization features: Godot's tr("KEY") and translation CSV files let the same UI show other languages; containers resize labels automatically when a translation is longer.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In what order does a Control look for a theme item?

    The most specific setting wins: an override on the node beats inherited themes, which beat the project and default themes.
  2. 2. What is a theme type variation for?

    A variation bundles styles, so you set theme_type_variation on a control instead of many overrides.
  3. 3. Which stretch mode keeps pixel art sharp by rendering at the design size and scaling the image?

    viewport mode renders at the base resolution and scales it; canvas_items re-renders at full resolution.
  4. 4. What does StyleBoxEmpty do on a Button's focus slot?

    StyleBoxEmpty is a stylebox that draws nothing.

Summary

  • A Theme defines colors, constants, fonts, icons and styleboxes per control type.
  • Lookup goes: local override, own theme, ancestor themes, project theme, default.
  • Use StyleBoxFlat for quick styling, theme type variations for reusable looks.
  • Set the base size, stretch mode and aspect in Project Settings; use anchors, safe areas and a UI scale option.

Next: Exporting Your Game