Class
UIListLayout
Positions sibling UI elements in rows or columns within the parent UI container.
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 SortOrder.Name or
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:
HorizontalFlexand/orVerticalFlexare not set toUIFlexAlignment.None.ItemLineAlignmentis not set toItemLineAlignment.Automatic.Wrapsistrue.
Properties 5#
HorizontalFlexUIFlexAlignment | Controls how to distribute extra horizontal space.ReadSafe |
ItemLineAlignmentItemLineAlignment | In a flex layout, defines the cross-directional alignment of siblings within a line.ReadSafe |
PaddingUDim | Amount of free space between each element.ReadSafe |
VerticalFlexUIFlexAlignment | Controls how to distribute extra vertical space.ReadSafe |
Wrapsboolean | Controls whether siblings within the parent container wrap.ReadSafe |
HorizontalFlex: UIFlexAlignment#
ReadSafe
When the list layout's FillDirection is
set to FillDirection.Horizontal, the
HorizontalFlex property specifies how
to distribute extra horizontal space in the parent container.
| Setting | Sibling Behavior |
|---|---|
Enum.UIFlexAlignment.None|None |
No flex behavior; siblings maintain their defined width. |
Enum.UIFlexAlignment.Fill|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 Enum.UIFlexAlignment.None|None setting, those three siblings will resize to fill the entire width. |
Enum.UIFlexAlignment.SpaceAround|SpaceAround |
Siblings maintain their defined width. Equal spacing is added on both sides of each sibling. |
Enum.UIFlexAlignment.SpaceBetween|SpaceBetween |
Siblings maintain their defined width. Equal spacing is added between siblings, but no additional space is added around siblings. |
Enum.UIFlexAlignment.SpaceEvenly|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
FillDirection.Vertical), the
HorizontalFlex property specifies how
to distribute the siblings across the horizontal cross‑direction. In
such layouts, a setting of 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: ItemLineAlignment#
ReadSafe
In a flex layout, defines
the cross-directional alignment of siblings within a line. See
ItemLineAlignment for visual examples.
| Setting | Sibling Behavior |
|---|---|
Enum.ItemLineAlignment.Automatic|Automatic |
Aligns the layout's siblings or the specific Class.UIFlexItem parent to the layout's Class.UIListLayout.HorizontalAlignment|HorizontalAlignment or Class.UIListLayout.VerticalAlignment|VerticalAlignment, depending on its Class.UIListLayout.FillDirection|FillDirection. |
Enum.ItemLineAlignment.Start|Start |
Aligns the layout's siblings or the specific Class.UIFlexItem parent to the line's top in a horizontal fill or the line's left in a vertical fill. |
Enum.ItemLineAlignment.Center|Center |
Aligns the layout's siblings or the specific Class.UIFlexItem parent to the line's center in either a horizontal or vertical fill. |
Enum.ItemLineAlignment.End|End |
Aligns the layout's siblings or the specific Class.UIFlexItem parent to the line's bottom in a horizontal fill or the line's right in a vertical fill. |
Enum.ItemLineAlignment.Stretch|Stretch |
Stretches the layout's siblings or the specific Class.UIFlexItem parent to fill the entire cross‑direction of the line in either a horizontal or vertical fill. |
