Quickstart: Build a Flexbox layout with FlexBuilder GUI

This is a short tutorial that will get you up and running with a simple GUI, using FlexBuilder for Unity3D.FlexContainer

Pre-requisites:

  • Unity3D
  • FlexBuilder (from the Unity Asset Store)

See also:

Note

This document contains embedded YouTube videos, if you are reading the PDF version they will not load - it's recommended you using the online version instead, part of the online manual at: http://docs.flexbuilder.ninja

Building a Layout

Every new layout has 4 steps:

  1. Select a RootFlexContainer to hold your layout, and control shared settings
  2. Add an initial FlexContainer to start configuring the layout
  3. Add lots of child FlexContainers and FlexItems to make an interesting layout
  4. For each FlexItem, add a UnityUI element (a button, or an image, or text, etc)

Creating a RootFlexContainer (RFC)

Right-click in the Hierarchy view, select 'Flexbox' from the menu, and select 'RootFlexContainer':

Configure the FlexItems and FlexContainers

Select your RootFlexContainer, and click 'Add Initial FlexContainer'.

Then add your layout to the FlexContainer, using nested FlexContainers with different orientations, padding, margins, etc.

In this example, we create three images side-by-side, automatically sized and positioned:

Add UI components to your FlexItems

Each FlexItem controls the size + shape + position of a single UI-element. Every place you want a new element - an Image, a Text, a Button - you need to add a new FlexItem (select the parent FlexContainer that you want to hold the new element, and click the "Add FlexItem" button).

Select your newly-created FlexItem, and then add a child UI component (or attach it directly to the FlexItem).

Note

Directly-attaching UI components to FlexItem GameObjects is supported, but it's an advanced setup, and can cause problems for larger/more complex layouts. It's recommended to add each UI component as a direct child of a FlexItem instead wherever possible.

Warning

Each FlexItem should have ONLY ONE Unity UI element attached to it, or as a child. Adding multiple to a single FlexItem is possible but is an advanced use and can generate hard-to-edit layouts

Common recipes

Center an item?

In legacy CSS centering things is difficult; in modern CSS it's easy - but items default to taking up the full space available, so first you have to tell the FlexItem to "stop taking all the space".

A FlexItem will - by default - take up all space for two reasons:

  1. In the direction of the parent FlexContainer (e.g. for a "row" container: horizontal), FlexItems default to "grow: 1", which causes them to take all the space they can
  2. In the perpendicular direction (e.g. for a "row" container: vertical), the container itself defaults to "stretching to fit" all child items

Here we add a single Unity Button, and set it to vertically-centered, then also make it horizontally-centered:

We can change both those defaults, causing the item to take up only as much space as it needs. This often causes an item to vanish (sizing itself to 0) if FlexBuilder cannot auto-detect a correct size. In that case, the standard approach is to provide an explicit "width" and "height" on the FlexItem itself.

Here we want an icon of fixed size (100x100 pixels); Flexbox initially expands it to fill all the space, but when we set it to take up only the space it needs, it is now the raw-image's size. So we override that by setting explicit width and height:

Tip

FlexBuilder is intelligent: when we specify the 'width' explicitly, and nothing is trying to control the height, it automatically uses the correct height to maintain the aspect-ratio of the image. However if the parent FlexContainer were stretching it vertically, overriding the default height, this wouldn't work and we'd need to explicitly set the 'height' as well as the 'width'

Note

UnityUI/RectTransform is famous for preventing you setting a specific 'size' without causing many bugs in your layout; Flexbox doesn't have that problem, and FlexBuilder fully integrates Flexbox's correct sizing into UnityUI, bypassing the bugs in RectTransform. You can always safely use "width" and "height" in a Flexbox layout

Create a list of rows?

This layout is used very frequently. One of the simplest cases: a main-menu with a list of buttons. Another common one: an inventory that has one row with an icon + text for each item.

Both are quick and easy to do. Here is an example of creating a list of rows, where each row is itself made up of multiple UnityUI elements:

Next Steps

Now you're ready to create your own UI. But it's also recommended you read through the docs in the "Guides and Docs" section in the left sidebar -- this will give you more detail on some of the features you can use, and how they'll help you build a UI.

If you're looking for feedback on the UI you're building, join us in the community Discord, and show us what you're making!