UIListLayout
A UIListLayout positions sibling UI elements in rows or columns within the parent UI container, based on the FillDirection. The Position and Rotation properties of each sibling GuiObject are either ignored or overridden by the list layout, while each sibling retains its defined Size unless the layout is configured to utilize a flex layout. See List and Flex Layouts for further information.
To control the layout order of siblings, set SortOrder to either Enum.SortOrder.Name or Enum.SortOrder.LayoutOrder, then rename siblings in alphanumerical order or set their LayoutOrder value, respectively. UIListLayout will automatically re‑layout elements when elements are added/removed, or if a sibling's Name or LayoutOrder changes.
Padding between siblings is controlled through the Padding property, and wrapping within the parent container's bounds through the Wraps boolean. Alignment of siblings within the parent container is controlled through HorizontalAlignment and VerticalAlignment unless the layout is configured to utilize a flex layout.
Note that there are performance implications of using a flex‑enabled list layout, since extra calculations are needed to calculate flex basis sizes, flexed sizes, and line wrapping. Flex is enabled on a UIListLayout when the following properties are set, or if any GuiObject sibling has a UIFlexItem parented to it:
- Wraps is true.
Summary
Properties
Controls how to distribute extra horizontal space.
In a flex layout, defines the cross-directional alignment of siblings within a line.
Amount of free space between each element.
Controls how to distribute extra vertical space.
Controls whether siblings within the parent container wrap.
The absolute size of space being taken up by the grid layout.
Determines the axis in which UI objects are laid out.
Determines the horizontal alignment of UI elements within the parent element.
Determines the order in which child UI objects are placed in a layout.
Determines the vertical alignment of UI elements within the parent element.
Properties
HorizontalFlex
When the list layout's FillDirection is set to Enum.FillDirection.Horizontal, the HorizontalFlex property specifies how to distribute extra horizontal space in the parent container.
| Setting | Sibling Behavior |
|---|---|
| None | No flex behavior; siblings maintain their defined width. |
| Fill | Siblings resize horizontally to fill the entire parent container, overriding their defined width. The number of siblings in a row remain unchanged; for example, if three siblings fit horizontally within the container's width under the None setting, those three siblings will resize to fill the entire width. |
| SpaceAround | Siblings maintain their defined width. Equal spacing is added on both sides of each sibling. |
| SpaceBetween | Siblings maintain their defined width. Equal spacing is added between siblings, but no additional space is added around siblings. |
| SpaceEvenly | Siblings maintain their defined width. Equal spacing is added both between and around siblings. |
Cross-Direction Behavior
In vertical list layouts (FillDirection set to Enum.FillDirection.Vertical), the HorizontalFlex property specifies how to distribute the siblings across the horizontal cross‑direction. In such layouts, a setting of Enum.UIFlexAlignment.Fill makes the siblings fill the entire horizontal space while vertical spacing adheres to VerticalFlex.
AutomaticSize Interaction
If GuiObject.AutomaticSize is enabled for a child of the UIListLayout in the FillDirection, it is interpreted as "automatic flex basis" and it defines the size of the GuiObject from which it can grow or shrink.
If GuiObject.AutomaticSize is enabled for a child of the UIListLayout in the cross‑direction, it is interpreted as "automatic cross size" and it defines the minimum size needed to contain all the child's content in the cross‑direction.
ItemLineAlignment
In a flex layout, defines the cross-directional alignment of siblings within a line. See Enum.ItemLineAlignment for visual examples.
| Setting | Sibling Behavior |
|---|---|
| Automatic | Aligns the layout's siblings or the specific UIFlexItem parent to the layout's HorizontalAlignment or VerticalAlignment, depending on its FillDirection. |
| Start | Aligns the layout's siblings or the specific UIFlexItem parent to the line's top in a horizontal fill or the line's left in a vertical fill. |
| Center | Aligns the layout's siblings or the specific UIFlexItem parent to the line's center in either a horizontal or vertical fill. |
| End | Aligns the layout's siblings or the specific UIFlexItem parent to the line's bottom in a horizontal fill or the line's right in a vertical fill. |
| Stretch | Stretches the layout's siblings or the specific UIFlexItem parent to fill the entire cross‑direction of the line in either a horizontal or vertical fill. |
Padding
Determines the amount of free space between each element, set to either a scale (percentage of the parent's size in the current direction) or an offset (static spacing value similar to pixel size).
VerticalFlex
When the list layout's FillDirection is set to Enum.FillDirection.Vertical, the VerticalFlex property specifies how to distribute extra vertical space in the parent container.
| Setting | Sibling Behavior |
|---|---|
| None | No flex behavior; siblings maintain their defined height. |
| Fill | Siblings resize vertically to fill the entire parent container, overriding their defined height. The number of siblings in a column remain unchanged; for example, if three siblings fit vertically within the container's height under the None setting, those three siblings will resize to fill the entire height. |
| SpaceAround | Siblings maintain their defined height. Equal spacing is added on both sides of each sibling. |
| SpaceBetween | Siblings maintain their defined height. Equal spacing is added between siblings, but no additional space is added around siblings. |
| SpaceEvenly | Siblings maintain their defined height. Equal spacing is added both between and around siblings. |
Cross-Direction Behavior
In horizontal list layouts (FillDirection set to Enum.FillDirection.Horizontal), the VerticalFlex property specifies how to distribute the siblings across the vertical cross direction. In such layouts, a setting of Enum.UIFlexAlignment.Fill makes the siblings fill the entire vertical space while horizontal spacing adheres to HorizontalFlex.
AutomaticSize Interaction
If GuiObject.AutomaticSize is enabled for a child of the UIListLayout in the FillDirection, it is interpreted as "automatic flex basis" and it defines the size of the GuiObject from which it can grow or shrink.
If GuiObject.AutomaticSize is enabled for a child of the UIListLayout in the cross‑direction, it is interpreted as "automatic cross size" and it defines the minimum size needed to contain all the child's content in the cross‑direction.
Wraps
Controls whether siblings within the parent container wrap to another line when their default size exceeds the width/height of the container's bounds.
