UIListLayout
Positions sibling UI elements in rows or columns within the parent UI container.
| Memory category | Instances |
|---|
Member index 7
Description
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 propertly, 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:
- HorizontalFlex and/or VerticalFlex are not set to UIFlexAlignment.None.
- ItemLineAlignment is not set to ItemLineAlignment.Automatic.
- Wraps is
true.
History 14
- 647 Change Category of VerticalFlex from Data to Alignment
- 647 Change Category of ItemLineAlignment from Data to Alignment
- 647 Change Category of HorizontalFlex from Data to Alignment
- 599 Add
- 599 Add ItemLineAlignment
- 599 Add
- 598 Add Wraps
- 598 Add VerticalFlex
- 598 Add HorizontalFlex
- 553 Change Default of Padding from to UDim(0, 0)
- 486 Change ThreadSafety of Padding from ReadOnly to ReadSafe
- 462 Change ThreadSafety of Padding from to ReadOnly
- 274 Add Padding
- 274 Add UIListLayout
Members 7
HorizontalFlex
| Type | Default | |
|---|---|---|
| UIFlexAlignment | None | |
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 |
|---|---|
| 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
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.
| Thread safety | ReadSafe |
|---|---|
| Category | Alignment |
| Loaded/Saved | true |
History 2
- 647 Change Category of HorizontalFlex from Data to Alignment
- 598 Add HorizontalFlex
ItemLineAlignment
| Type | Default | |
|---|---|---|
| ItemLineAlignment | Automatic | |
In a flex layout, defines the cross-directional alignment of siblings within a line. See 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. |
| Thread safety | ReadSafe |
|---|---|
| Category | Alignment |
| Loaded/Saved | true |
History 2
- 647 Change Category of ItemLineAlignment from Data to Alignment
- 599 Add ItemLineAlignment
Padding
| Type | Default | |
|---|---|---|
| UDim | 0, 0 | |
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).
| Thread safety | ReadSafe |
|---|---|
| Category | Appearance |
| Loaded/Saved | true |
VerticalFlex
| Type | Default | |
|---|---|---|
| UIFlexAlignment | None | |
When the list layout's FillDirection is
set to 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
FillDirection.Horizontal), the VerticalFlex property specifies
how to distribute the siblings across the vertical cross direction. In
such layouts, a setting of 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.
| Thread safety | ReadSafe |
|---|---|
| Category | Alignment |
| Loaded/Saved | true |
History 2
- 647 Change Category of VerticalFlex from Data to Alignment
- 598 Add VerticalFlex
Wraps
| Type | Default | |
|---|---|---|
| bool | false | |
Controls whether siblings within the parent container wrap to another line when their default size exceeds the width/height of the container's bounds.
| Thread safety | ReadSafe |
|---|---|
| Category | Behavior |
| Loaded/Saved | true |