Responsive UI

Project UI scaling

Open Settings → UI Scaling with a project open. Set Design width and Design height to the resolution you design at, choose Fit proportionally, and save with Save project scaling. The initial values are 1920 × 1080 and 100%. Build/synchronize your packages before checking the result in Unreal.

At 1280 × 800, this configuration uses min(1280 / 1920, 800 / 1080) = 0.667. A 125 px button occupies about 83 physical pixels. Its CSS does not change. The logical layout area is 1920 × 1200: different aspect ratios gain space instead of mandatory letterboxing. Text, icons, clipping and pointer coordinates use the same scale. Preview displays UI …% separately from its canvas zoom.

UI size (%) multiplies the result. No scaling ignores design resolution but still applies that multiplier. New Studio projects use proportional fit. Older projects keep host scaling until you save this setting. For these projects, Mode explicitly shows Legacy host (not configured), not an inactive Fit preset. Select Fit or No scaling before saving. The active legacy status remains visible until the project setting has been saved. Changing Preview resolution then recalculates the applied UI scale without changing Preview zoom. After an external edit to calmui.config.json, reload the project so Studio reads the updated configuration.

The shared project source is calmui.config.json:

{
  "uiScaling": {
    "mode": "fit",
    "designWidth": 1920,
    "designHeight": 1080,
    "percent": 100
  }
}

All four fields are required. Modes are fit and none; dimensions are integers from 1 to 16384, and percent is an integer from 25 to 400. The compiler reports invalid settings rather than silently ignoring them. Packages carry this setting for Shipping. Explicit project scaling replaces Unreal screen DPI scaling; it is not multiplied by it. World-space surfaces retain their explicit render-target size and device scale.

Responsive tests use the logical layout area and check minimum focus sizes in physical pixels. Check readability on handhelds: proportional fit can make text too small even when the layout has no overflow.

Layout breakpoints

Use a media query in the View's CSS to change its layout at a chosen width:

.menu { width: 480px; }
@media (max-width: 850px) {
  .menu { width: 100%; padding: 16px; }
}

The rule applies to an element with class="menu". Below 850 pixels of logical View width, it fills the available width and gains padding. Save and switch between narrow and wide resolution presets in Preview. Use Tests → Responsive for reported layout problems. These widths are measured before display scaling.

Safe areas

Fixed overlays stay outside flex layout. A modal using position: fixed, left: 0, top: 0, width: 100%, height: 100% and box-sizing: border-box covers the logical viewport without moving its siblings. Parent gap does not add margins to the modal; its padding stays inside those viewport dimensions.

A safe area keeps content away from a display cutout or a TV edge. Add these values to the root container when your design needs that padding:

.view {
  padding: env(calmui-safe-area-inset-top)
           env(calmui-safe-area-inset-right)
           env(calmui-safe-area-inset-bottom)
           env(calmui-safe-area-inset-left);
}

CalmUI does not add safe padding automatically. The default value is zero, and the names intentionally differ from browser safe-area-inset-* values. Unreal converts platform margins through the effective project or host scale; a split-screen Local Player receives only the outer edges it touches. Studio Preview offers zero, TV 5%, display-cutout, and custom profiles.