UIListLayout & UIGridLayout in Roblox — Complete Roblox Guide

When to use UIListLayout

UIListLayout stacks children in a single direction — vertical or horizontal. It is perfect for leaderboards, settings rows, chat messages, hotbar slots, and dialogue choice buttons. The layout reads each child's LayoutOrder property and sorts them ascending.

local list = Instance.new("UIListLayout")
list.FillDirection = Enum.FillDirection.Vertical
list.HorizontalAlignment = Enum.HorizontalAlignment.Center
list.VerticalAlignment = Enum.VerticalAlignment.Top
list.SortOrder = Enum.SortOrder.LayoutOrder
list.Padding = UDim.new(0, 8)
list.Parent = container

When to use UIGridLayout

UIGridLayout arranges children in a 2D grid with fixed cell size. Use it for inventories, shop cards, ability hotbars, and pet collections. Cells stay square regardless of parent size, and rows wrap automatically.

local grid = Instance.new("UIGridLayout")
grid.CellSize = UDim2.new(0, 100, 0, 100)
grid.CellPadding = UDim2.new(0, 8, 0, 8)
grid.FillDirection = Enum.FillDirection.Horizontal
grid.SortOrder = Enum.SortOrder.LayoutOrder
grid.Parent = container

LayoutOrder — the property nobody mentions

Both layouts honor each child's LayoutOrder when SortOrder is set to LayoutOrder. Leave gaps (10, 20, 30) instead of (1, 2, 3) so you can insert items without renumbering.

Wrapping in a ScrollingFrame

For long lists or grids, parent the layout container inside a ScrollingFrame and set AutomaticCanvasSize to Y. The ScrollingFrame reads the layout's AbsoluteContentSize and resizes its CanvasSize to match.

local scroll = Instance.new("ScrollingFrame")
scroll.Size = UDim2.new(1, 0, 1, 0)
scroll.CanvasSize = UDim2.new(0, 0, 0, 0)
scroll.AutomaticCanvasSize = Enum.AutomaticSize.Y
scroll.ScrollBarThickness = 6
scroll.Parent = parent

local list = Instance.new("UIListLayout")
list.SortOrder = Enum.SortOrder.LayoutOrder
list.Padding = UDim.new(0, 8)
list.Parent = scroll

UIPadding — the inset you keep forgetting

Layouts measure spacing between children, not from the container edge. Without UIPadding, your top item sits flush against the container border. Add a UIPadding sibling with PaddingTop / PaddingBottom / PaddingLeft / PaddingRight to inset content.

Performance and lifecycle gotchas

Layouts run on every frame change, but cost is negligible until ~200 children. Set LayoutOrder before parenting to avoid double-sort. Do not put a UIListLayout and a UIGridLayout under the same parent — Roblox honors the first one and ignores the second silently.

Step-by-step summary

1. 1

   Pick the right layout object

   UIListLayout for stacks, UIGridLayout for 2D grids.

2. 2

   Set padding and sort order

   Use LayoutOrder for explicit ordering and Padding for gaps.

3. 3

   Wrap in a ScrollingFrame for long lists

   Set AutomaticCanvasSize = Y so the canvas resizes automatically.

4. 4

   Add UIPadding for edge inset

   Add 12–24 px on each side for breathing room.

5. 5

   Test with dynamic content

   Add and remove children at runtime to confirm reflow.

FAQ