Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท UI and Events

UI Layout, UDim2 and Responsive Design

Learn how UDim2 scale and offset, AnchorPoint and layout objects such as UIListLayout and UIGridLayout make Roblox interfaces fit phones, tablets and PCs.

Roblox runs on phones, tablets, consoles and computers. A button that looks perfect on your 1920-pixel monitor can be tiny or off-screen on a phone. The cure is to describe sizes and positions relative to the parent instead of in fixed pixels. Roblox does this with a special value called UDim2.

This lesson explains UDim2, anchor points, and the layout objects that arrange children for you. The Roblox calls are shown read-only; the runnable examples are JavaScript stand-ins that do the same arithmetic so you can see the numbers.

What is a UDim2?

Size and Position are UDim2 values. A UDim2 holds four numbers: a scale and an offset for the X axis, and a scale and an offset for the Y axis.

LUA
frame.Size = UDim2.new(0.5, 0, 0.2, 0)
-- width  = 50% of the parent's width  + 0 pixels
-- height = 20% of the parent's height + 0 pixels

frame.Size = UDim2.new(0, 200, 0, 50)
-- exactly 200 by 50 pixels, on every screen
  • Scale is a fraction of the parent's size. 1 means the full parent width or height.
  • Offset is a fixed number of pixels added on top.

The two combine: UDim2.new(0.5, -20, 0, 40) is half the parent's width minus 20 pixels, and 40 pixels tall. You can also write UDim2.fromScale(0.5, 0.2) and UDim2.fromOffset(200, 50) when you use only one kind.

A top-level ScreenGui child uses the whole screen as its parent, so scale values there are fractions of the screen. A child nested inside a frame uses that frame as its parent.

AnchorPoint

Position places an object's anchor point. By default the anchor is the top-left corner, Vector2.new(0, 0). To centre an object you set both the position and the anchor:

LUA
panel.AnchorPoint = Vector2.new(0.5, 0.5)
panel.Position = UDim2.fromScale(0.5, 0.5)

The anchor (0.5, 0.5) is the middle of the object, so the object's middle lands in the middle of the parent. Anchors of (1, 0) pin the top-right corner, useful for close buttons.

Scale or offset?

Scale A fraction of the parent.
Offset A fixed pixel count.
Mix them Half the width minus 20 px.

Use scale for layout, offset for small fixed gaps.

1 / 2

Helpers that keep shapes right

Scale alone can stretch things. A square icon sized 0.2, 0.2 becomes a wide rectangle on a wide screen. Add these children to fix common problems:

  • UIAspectRatioConstraint keeps width divided by height at a fixed value, such as 1 for a square.
  • UISizeConstraint sets a minimum and maximum pixel size, so a button never gets tiny or huge.
  • UITextSizeConstraint limits TextScaled text so it never becomes unreadable.
  • UIPadding adds space inside a frame, UICorner rounds corners and UIStroke draws an outline.

Layout objects

Positioning ten buttons by hand is tedious. A layout object placed inside a container arranges all of its siblings automatically.

Layout What it does
UIListLayout Stacks children in a row or a column; set FillDirection, Padding, SortOrder
UIGridLayout Arranges children in a grid of equal cells (CellSize, CellPadding)
UITableLayout Rows and columns that size to their content
UIPageLayout Shows one child at a time and slides between pages

With SortOrder set to LayoutOrder, each child's LayoutOrder number decides its position. Use steps of 10 so you can insert items later.

LUA
local list = Instance.new("UIListLayout")
list.FillDirection = Enum.FillDirection.Vertical
list.Padding = UDim.new(0, 8)
list.SortOrder = Enum.SortOrder.LayoutOrder
list.Parent = menuFrame

For a long list, use a ScrollingFrame and set AutomaticCanvasSize to Y, so the scrollable area grows with the content.

Runnable stand-in: resolving a UDim2

This JavaScript code computes the pixel size and position that Roblox would produce. Change the parent size to imitate a phone and a PC.

JS Resolve UDim2 sizes (JavaScript stand-in)

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

No output.

The scaled panel grows with the screen. The fixed button keeps its pixel size, which is why it feels huge on a phone and tiny on a big monitor.

JS Simulate UIListLayout and a grid

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

No output.

Notice how the narrower frame wraps into more rows. A real UIGridLayout reflows in the same way, which is exactly what you want on a phone.

Tips for good mobile UI

  • Design for the smallest screen first, then check the large one. Studio's Device Emulator (Test tab) previews phones and tablets.
  • Keep touch targets at least about 44 pixels tall.
  • Leave a margin near the screen edges; some devices have notches. Set ScreenInsets on the ScreenGui if needed.
  • Use TextScaled together with a UITextSizeConstraint.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does UDim2.new(0.5, 0, 1, 0) mean for a Size?

    The numbers are xScale, xOffset, yScale, yOffset. xScale 0.5 is half the width and yScale 1 is the whole height.
  2. 2. How do you centre an object inside its parent?

    The position puts the anchor point in the middle of the parent, and an anchor of 0.5, 0.5 is the middle of the object itself.
  3. 3. Which object keeps an icon square on every screen shape?

    UIAspectRatioConstraint holds width over height at a fixed ratio, such as 1 for a square.
  4. 4. What controls the order of children in a UIListLayout when SortOrder is LayoutOrder?

    With SortOrder set to LayoutOrder, lower LayoutOrder values come first.

Summary

  • UDim2 combines scale (a fraction of the parent) and offset (pixels) for width, height and position.
  • AnchorPoint chooses which point of the object Position refers to; (0.5, 0.5) centres it.
  • Constraints (UIAspectRatioConstraint, UISizeConstraint, UITextSizeConstraint) stop scaled UI from distorting.
  • UIListLayout and UIGridLayout arrange children for you and reflow on small screens.
  • Test with the Device Emulator, and design for the smallest screen first.

Next: Buttons and Events