[Update] August 20, 2024
Flex is now live on all platforms!
Hi Developers!
We’re excited to announce the client release of Flex for UIListLayout! Thank you for all your feedback, messages, and excitement around this feature during the Studio Beta. Flex is a set of new UIListLayout features that allows your UI content to effortlessly fill a dynamically-sized UI container using these new features:
- Multiline wrapping
- Growing items to fill empty space / shrinking items if they don’t fit
- Distributing empty space between elements
- Custom per-item line alignment options
Check out UIListLayout and UIFlexItem for further documentation.
Please note that Flex is live on all client devices except Quest VR today. If you’re planning to enable your experience on Quest, we recommend temporarily avoiding the use of Flex in your implementation. We’re actively working on resolving bugs here and will keep you all updated.
Update: Flex is now live on all platforms!
Terminology
- Flex container: a GuiBase2D with a UIListLayout child
- Flex direction (or fill direction): the direction specified by UIListLayout.FillDirection
- Cross direction: direction perpendicular to the fill direction
- Flex item: a GuiObject child in a flex container
- Basis size: the size of a flex item before stretching/growing is applied
- Flex size: the size of a flex item after stretching/growing is applied
-
Flex line: a rectangle within a container containing multiple flex items
- The line’s flex size is the width or height of the container, depending on UIListLayout.FillDirection
- The line’s cross size is determined by the largest item cross size in the line
- The line’s rectangle always completely contains every item in the line
How to create with Flex
Let’s look at a simple example of making a “spacer” element that fills empty space in a container.
- Create a UIListLayout containing two TextLabels and the “spacer” element, a Frame.
- Set the TextLabels to a known size, such as 100 x 100px.
- Add a UIFlexItem component to the spacer Frame.
- Set the UIFlexItem.FlexMode = Fill so that the spacer fills the remaining space.
Your setup should look like this:
If you resize the parent container, notice that the spacer fills up the extra horizontal space between the two TextLabels!
Example: Shop UI
Flex features can be used across multiple UI elements to create a holistic feature, like a shop! We made a Flex demo place that uses all the new Flex features so you can get a taste of Flex in action. To access this place in Studio, go to the link above, click the 3 dots in the upper right corner, and click “Edit in Studio”.
Here’s what you’ll see when you open this place:
As you adjust the screen size of Studio, you’ll see how the Shop UI adjusts to small and large screen sizes to display the same information efficiently. All the shop items are accessible regardless of screen size – Flex ensures that the text isn’t too small to read or the buttons aren’t too small to tap on.
In the Explorer widget, you can find the instance tree:
Let’s dive deeper into the Flex features we used here:
- The ScrollingFrame has a UIListLayout component with HorizontalFlex = Fill and VerticalFlex = Fill. This tells each item in the list to grow horizontally and vertically to fit the container, if there is room.
- The UIListLayout has Wraps = true which allows the items to take up multiple lines.
- The icons have a UIFlexItem component with FlexMode = Custom and GrowFactor = 0.5, so they grow half as much as the text (which has GrowFactor 1 by default).
- Each item has a UISizeConstraint minSize of 120px in the Y direction, preventing the height of each item from being squished too much.
- The shop is wrapped in a ScrollingFrame so that overflowing items can be scrolled to on small screens.
- The ScrollingFrame has AutomaticCanvasSize = Y so that the canvas is sized to fit the content.
To the user, here’s how this UI would look on some different mobile and desktop screens:
APIs
New UIListLayout Properties
| Property | Value Options | Description |
|---|---|---|
| UIListLayout.FillDirection |
Horizontal, Vertical (default) |
The main axis aka flex direction of the layout. |
| UIListLayout.Wraps |
False (default), True
|
If true, allows multiple content lines to be created perpendicular to the FillDirection. |
| UIListLayout.HorizontalFlex |
None (default), Fill, SpaceAround, SpaceBetween, SpaceEvenly
|
If not None, distribute extra horizontal space using this strategy. |
| UIListLayout.VerticalFlex |
None (default), Fill, SpaceAround, SpaceBetween, SpaceEvenly
|
If not None, distribute extra vertical space using this strategy. |
| UIListLayout.ItemLineAlignment |
Automatic (default), Start, Center, End, Stretch
|
Cross-axis alignment of items within each line. |
New UIFlexItem Instances
| Property | Value Options | Description |
|---|---|---|
| UIFlexItem.FlexMode: | Enum.UIFlexMode None (default), Grow, Shrink, Fill, Custom |
How the parent GuiObject should grow or shrink with available space in the parent UIListLayout. |
| UIFlexItem.ItemLineAlignment: | Enum.ItemLineAlignment Automatic (default), Start, Center, End, Stretch |
Cross-axis alignment of this specific instance within the line. |
| GrowRatio: | float Positive number |
If FlexMode=Custom, and there is empty space in the line, this is the weighting factor for distributing the empty space to this specific item in order to fill the line. This property is only shown in Studio if FlexMode=Custom. |
| ShrinkRatio: | float Positive number |
If FlexMode=Custom, and there is overflow in the line, this is the weighting factor for shrinking this specific item in order to fit all items in 1 line. This property is only shown in Studio if FlexMode=Custom. |
New Enums
UIFlexAlignment
| Enum.UIFlexAlignment Value | Description |
|---|---|
| None (default) | How the parent GuiObject should grow or shrink with available space in the parent UIListLayout. |
| Fill | Set all child items to have an effective GrowRatio=1 and ShrinkRatio=1. |
| SpaceAround | Distribute space evenly between all items in the flex direction. The start and end padding is half the between-element padding. Note for SpaceAround, SpaceBetween, and SpaceEvenly, the spacing size is at least UIListLayout.Padding.
 |
| SpaceBetween | Distribute space evenly between all items in the flex direction. The start and end padding is zero. 
|
| SpaceEvenly | Distribute space evenly between all items in the flex direction. The start and end end padding is equal to the between-element padding. 
|
ItemLineAlignment
| Enum.ItemLineAlignment Value | Description |
|---|---|
| Automatic (default) | Follow the UIListLayout.HorizontalAlignment or UIListLayout.VerticalAlignment, depending on the FillDirection. This is the default value for backwards-compatibility. |
| Start | Align items within each line to the top for FillDirection.Horizontal or left for FillDirection.Vertical. |
| Center | Align items in each line to the center of the line. |
| End | Align items in each line to the bottom for FillDirection.Horizontal, or right for FillDirection.Vertical. |
| Fill | Fill entire line cross direction, overriding the original item cross size. |
UIFlexMode
| Enum.UIFlexMode | Effective GrowRatio | Effective ShrinkRatio |
|---|---|---|
| None (default) | 0 | 0 |
| Grow | 1 | 0 |
| Shrink | 0 | 1 |
| Fill | 1 | 1 |
| Custom | UIFlexItem.GrowRatio | UIFlexItem.ShrinkRatio |
Limitations
- How many items can I include within a Flex layout? While there is no hard limit, we recommend having less than 1000 items in your Flex layout to maintain performance quality. We are working to expand this capability in the future.
- Can I use AutomaticSize and Flex together? There are some interactions between AutomaticSize and UIFlexItem that are not currently supported, e.g. using non-zero anchor points, scaled size-items, scaled padding, and TextScaled. We are working to address these issues in the future.
Made with love
Flex Layouts was made possible due to the remarkable contributions of @stadium_parkour2, @uiuxartist, @EGOTISMS, @CharlieGordonnn, @DrRanchDressing, @darthskrill, and @Slim_Fandango. Thanks for all your help and support in making Flex Layouts! 
We can’t wait to hear your thoughts on Flex Layouts and see all the amazing things you create! Let us know about your experience and if you encounter any issues! 
