/responsive-ui

name: responsive-ui
description: Use when handling multiple resolutions — stretch modes, aspect ratios, DPI scaling, and mobile/desktop adaptation

Responsive UI in Godot 4.3+

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

> **Related skills:** **godot-ui** for Control node layout and themes, **export-pipeline** for platform-specific export settings, **godot-project-setup** for initial project resolution settings, **input-handling** for touch vs desktop input adaptation, **localization** for layout adjustments per locale, **mobile-development** for safe-area and notch handling.

---

1. Project Settings for Resolution

Configure base resolution and stretch behaviour in `Project > Project Settings > Display > Window`.

Key settings and their keys in the `[display]` section of `project.godot`:

| Setting | project.godot key | Recommended value | |---|---|---| | Viewport width | `window/size/viewport_width` | `1920` (or your base design width) | | Viewport height | `window/size/viewport_height` | `1080` (or your base design height) | | Stretch mode | `window/stretch/mode` | `canvas_items` (most games) | | Stretch aspect | `window/stretch/aspect` | `expand` (fill screen) or `keep` (letterbox) | | Scale factor | `window/stretch/scale` | `1` | | Scale mode | `window/stretch/scale_mode` | `fractional`; `integer` for pixel art |

> **Godot 4.7+:** Projects **newly created** in Godot 4.7 already default `display/window/stretch/mode` to `canvas_items` and `display/window/stretch/aspect` to `expand` (previously `disabled` / `keep`) — the recommendations above are now the out-of-the-box values. Projects created on older versions are unchanged (the property default is still `disabled`), so set both explicitly when upgrading. See the [4.7 migration guide](https://docs.godotengine.org/en/latest/tutorials/migrating/upgrading_to_godot_4.7.html).

The engine reads these settings once at startup; changing them with `ProjectSettings.set_setting()` later has no effect. At runtime, set the matching `Window` properties instead:

**GDScript:**

# Read current viewport size
var viewport_size: Vector2 = get_viewport().get_visible_rect().size

# Change stretch mode at runtime (takes effect immediately)
get_window().content_scale_mode = Window.CONTENT_SCALE_MODE_CANVAS_ITEMS

**C#:**

// Read current viewport size
Vector2 viewportSize = GetViewport().GetVisibleRect().Size;

// Change stretch mode at runtime (takes effect immediately)
GetWindow().ContentScaleMode = Window.ContentScaleModeEnum.CanvasItems;

---

2. Stretch Mode Comparison

| Mode | `project.godot` value | Rendering | Best For | |---|---|---|---| | `canvas_items` | `"canvas_items"` | Rendered at the window's resolution; 2D nodes and UI are scaled from the design resolution, so text stays sharp | Most 2D and UI-heavy games | | `viewport` | `"viewport"` | Entire viewport is rendered at design resolution and stretched; no sub-pixel blending | Pixel art games needing pixel-perfect output | | `disabled` | `"disabled"` | No automatic scaling; the viewport is the window size, so a bigger window shows more at the same pixel size (anchors and containers still lay out) | Complex custom scaling, 3D games with a Control HUD |

**When to choose each:**

• **`canvas_items`** — Default recommendation. Smooth scaling at any resolution. UI built with `Control` nodes and anchors responds naturally. Text and icons stay crisp at high DPI when combined with `content_scale_factor`.
• **`viewport`** — Locks rendering to the design resolution. Combined with integer scaling and nearest-neighbour filtering it gives a classic pixel-perfect look. Avoid for high-DPI displays unless you intentionally want chunky pixels.
• **`disabled`** — Use when you need full manual control, e.g. a 3D game where the UI must adapt to safe areas or unusual aspect ratios without Godot scaling it.

---

3. Aspect Ratio Handling

Set via `Project > Project Settings > Display > Window > Stretch > Aspect` or the `window/stretch/aspect` key.

| Mode | Visual Result | When to Use | |---|---|---| | `keep` | Letterbox (black bars top/bottom) or pillarbox (bars left/right) — design rect is preserved exactly | Games with a fixed layout that must not be cropped (e.g. score-based arcade, puzzle) | | `expand` | Screen is fully filled; the visible game area grows on wider or taller displays | Action games, platformers — more visible play area is a bonus, not a problem | | `keep_width` | Width is fixed; height expands on taller screens (mobile portrait) | Portrait mobile games where horizontal alignment is strict | | `keep_height` | Height is fixed; width expands on wider screens (landscape) | Landscape games where vertical alignment is strict (e.g. side-scroller HUD) |

**`expand` with adaptive UI** is the most versatile choice for games targeting both desktop and mobile. Anchor your HUD elements to screen edges so they follow the expanded visible area.

---

4. Pixel Art Setup

For crisp pixel-art games: `Project Settings → Display → Window → Stretch → Mode = viewport`, base resolution at native pixel size (e.g., 320×180), `Window Width/Height Override` (e.g. 1280×720) for a larger window when testing. Use integer scaling (`Stretch → Scale Mode = integer`) to avoid uneven pixels.

> See [references/pixel-art-setup.md](references/pixel-art-setup.md) for full project settings, integer-scaling script, nearest-neighbour filter overrides.

---

5. DPI Scaling

For retina / high-DPI displays: set `content_scale_factor` to scale the entire UI proportionally. Query `DisplayServer.screen_get_dpi()` at runtime for adaptive scaling per device.

> See [references/dpi-scaling.md](references/dpi-scaling.md) for the `content_scale_factor` recipe and DPI-querying patterns.

---

6. Mobile Considerations

Four mobile-specific concerns: **touch input** (tap, swipe, multi-touch), **safe-area insets** (notch / dynamic island avoi