UI Toolkit: Introduction and Flexbox Layout

Hi everyone,

This is our second article in the UI Toolkit - Dragon Crashers sample (2022 LTS update) series. Today we’ll cover flexbox layout in UI Toolkit.

Unity UI Toolkit uses a CSS-like styling system that allows for more flexible and sophisticated designs. One of the key components is a flexbox layout system, which makes responsive designs easier to achieve and may be familiar to those who also worked with web development. In this article we explain some of those key components in UI Toolkit and how to use them in your applications.

This article is based on a chapter in the e-book, User interface design and implementation in Unity, where artists, designers, and developers can find tips and best practices for building sophisticated interfaces with Unity’s two UI systems, Unity UI and UI Toolkit.

UI Toolkit workflow

UI Toolkit is a collection of features, resources, and tools for developing runtime UI and Editor extensions in Unity 2021 LTS and later versions. It’s designed from the ground up to make it easier to create, debug, and optimize user interfaces, and to control how they are presented and interacted with.

Each interface built with UI Toolkit involves several parts working together. Let’s do a quick break down before we dive into the specifics of flexbox:

UI Document (UXML): This references Unity Extensible Markup Language (UXML) and is inspired by HTML, XAML, and XML languages. It defines the structure of the user interface and holds information about the layout’s hierarchy. It can be styled using inline style rules and style sheets. The UXML Document is represented with a tree-like structure of UI elements, laying out parent-child relationships and setting up the initial properties of those elements.

  • Create the asset via Assets > Create > UI Toolkit > UI Document. This asset is added to your project folder which can then be opened in the UI Builder.

Style Sheet (USS): Inspired by Cascading Style Sheets (CSS) from HTML, a style sheet in UI Toolkit contains cascading rules about style properties which can affect the visual layout of a UXML. For example, you can define a certain styling for how all your buttons and text fonts should look in one place and then this styling propagates across your entire project.

  • Create this asset via Assets > Create > UI Toolkit > Style Sheet. This asset is added to your project folder, which can then be added to an open UXML file in the UI Builder.

Theme Style Sheet (TSS): Theme Style Sheets make it easy to switch between different visual appearances (themes) for your UI. This can be particularly useful for scenarios like creating a day/night mode for an application, offering multiple skins for a game UI, or adapting the UI appearance based on user preferences.

This asset is a collection of TSS and USS files that determine what Panel Settings to use (see image below).

To properly visualize these assets in the Scene view, they need to work together with the components and assets in the image below.

UI Document Component: This component defines what UXML will be shown in the Game view, and connects that UI Toolkit asset to a GameObject. It can be added to a GameObject in the Editor Hierarchy, and can specify what Panel Settings to use. The Sort Order field determines how this document shows up in relation to other UI Documents using the same Panel Settings.

  • Add this component to a GameObject using the Add Component menu in the Inspector, or right-click in the Hierarchy and select UI Toolkit > UI document, which will automatically assign Panel Settings.

Panel Settings: This asset defines how the UI document component will be instantiated and visualized at runtime. It’s possible to have multiple Panel Settings to enable different styles for the UIs. If your game includes HUD or a minimap, for instance, these special UIs could each have their own Panel Settings.

  • Create the asset on its own via Assets > Create > UI Toolkit > Panel Settings Asset. This asset is added to your project folder, which can then be added to a UI Document component on a GameObject.

Once saved to the Assets folder, artists and designers can work with UXML and USS files in the UI Builder (Window > UI Toolkit > UI Builder). UI Builder is a visual tool that helps creators build and edit interfaces without writing code.

Unlike Unity UI, UI Toolkit elements won’t appear in the Scene view. UI artists will spend most of their time in the UI Builder, which includes an option to preview the Game view at their runtime.

Flexbox basics

UI Toolkit positions visual elements based on Yoga, an HTML/CSS Layout engine that implements a subset of Flexbox. If you’re unfamiliar with Yoga and Flexbox, the chapter “Flexbox basics”, in the User interface design and implementation e-book, gets you up to speed on the principles behind UI Toolkit’s Layout engine.

Flexbox architecture is great for developing complex, well-organized layouts. Here are some of the advantages:

  • Responsive UI: Flexbox organizes everything into a network of boxes or containers. You can nest these elements as parents and children and arrange them spatially onscreen using simple rules. Children containers respond automatically to changes in their parent containers. A responsive layout adapts to different screen resolutions and sizes, accommodating the differences in the end devices across multiple platforms.
  • Organized complexity: Styles define simple rules that control the aesthetic value of a visual element. One style can be applied to hundreds of elements at once, with changes immediately reflected on the entire UI. This centers UI design around consistent reusable styles rather than working on the appearance of individual elements.
  • Decoupled logic and design: UI layouts and styles are decoupled from the code. This helps designers and developers work in parallel without breaking dependencies.

Visual elements

In UI Toolkit, the fundamental building blocks of each interface are their visual elements. A visual element is the base class of every UI Toolkit element (buttons, images, text, etc.). Think of them as UI Toolkit equivalents of Game Objects.

A UI Hierarchy of one or more visual elements is called a Visual Tree. In UI Toolkit, combinations of multiple visual elements are stored in the UI Document files, with the extension .uxml. A UXML file contains information related to the Hierarchy, as well as its styling and the layout of visual elements. To build your first UI Toolkit interface, create a new UI Document from the Assets menu (Create > UI Toolkit > UI Document). Open the file from the Project window or directly from UI Builder (Window > UI Toolkit > UI Builder).

Tip: The UI Builder documentation contains an Interface overview so you can get better acquainted with the window’s interface. See the Getting started section if you’re new to UI Builder.

Before diving deeper into UI Toolkit, you’ll need to understand the fundamentals of Flexbox Layout, which can be demonstrated with basic visual elements in the UI Builder. Using Flexbox requires an understanding of how to lay out elements in the interface according to the engine rules.

You can drag visual elements from the Library into the Hierarchy view and arrange them into parent-child relationships. In Flexbox Layout, modifying a parent (the Flex container) impacts its children (the Flex items).

Common settings in the Inspector

Let’s examine some of the most common settings in the Inspector that affect the visual tree.

Positioning visual elements

When mocking up a UI, approach each screen as a separate group of visual elements. Think about how to break them down into visual tree hierarchies. When defining child visual elements, the UI Builder offers two position options: Relative positioning is based on an element’s position relative to its original position, while absolute positioning is based on an element’s position relative to its nearest positioned parent visual element.

  • Relative positioning: This is the default setting for new visual elements. Child elements follow the Flexbox rules of the parent containers. Relative positioning resizes and moves elements dynamically based on the parent element’s size or style rules, or the child element’s size and style rules.

  • Absolute positioning: The position of the visual element anchors to the parent container. Rules like Margins or Maximum Size still apply, but it doesn’t follow the Flexbox rules from the parent. The element overlays on top of the parent container.

Whether in Absolute or Relative positioning, you can use the Canvas to move

elements around and adjust their placement.

Size settings

Remember that visual elements are simply containers. By default, they don’t take up any space unless they are filled with other child elements that already have a specific size, or you set them to a particular Width and Height. The Width and the Height fields define the size of the element. These impact how the Flex settings can resize the elements based on available space.

size settings

Flex settings

The Flex settings can affect your element’s size when using Relative positioning. It’s recommended that you experiment with elements to understand their behavior firsthand. Basis refers to the default Width and Height of the item before any Grow or Shrink ratio operation occurs:

  • If Grow is set to 1, this element will take all the available vertical or horizontal space in the parent element.
  • If Grow is set to 0, the element does not grow beyond its current Basis (or size).
  • If Shrink is set to 1, the element will shrink as much as required to fit in the parent element’s available space.
  • If Shrink is set to 0, the element will not shrink and will overflow if necessary.

The Direction setting defines how child elements are arranged inside the parent. Child elements higher in the Hierarchy menu appear first. Elements at the end of the Hierarchy appear last.

The Wrap setting tells the Layout system whether elements should try to fit into one column or row (No Wrap). Otherwise, they appear in the next row or column (Wrap or Wrap reverse).

Align settings

The Align settings determine how child elements line up to their parent element. Set the Align > Align items in the parent to line up child elements to the start, center or end. These options affect the cross-axis (perpendicular to the row or column in the Flex > Direction).

The Stretch option also works along the cross-axis, but the Min or Max values from the size can limit the effect (this is the default). Meanwhile, the Auto option indicated that the Layout engine can automatically choose one of the other options based on other parameters. It’s recommended that you select one of the options for more control over the layout, and mainly use the Auto option for special use cases.

Margin and padding settings

Use the Margin and Padding settings to define empty spaces around your visual elements and their content. Unity uses a variation of the standard CSS box model:

  • The content Space holds key visual elements (text, images, controls, etc.)
  • Padding defines an empty area around the Content space, but inside the Border.
  • The Border defines a boundary between Padding and the Margin. This can be colored and rounded. If given a thickness, the Border expands inward.
  • Margin is similar to Padding but defines an area outside the Border.

Tip: In UI Builder, you can create empty Margins with either the Position or Margin settings. For elements that have Relative position, use the Margin settings. For elements with Absolute position, use the Position settings.

Background and images

In UI Toolkit, any visual element can serve as an onscreen image. Simply swap the background to show a texture or sprite. You can fill in a color or image to change the element’s appearance. This is helpful for wireframing. Bright colors with contrast can show how different elements look next to one another and respond to changes in their containers.

Variable or fixed measuring units

In UI Builder, you’ll encounter four parameters that define the distance and size of the elements:

  • Auto: This is the default option for size and position. The Layout system calculates the elements’ values based on both the parent and child elements’ information.
  • Percentage: The unit equals a percentage of an element’s container and changes dynamically with the parent’s Width and Height. Working with percentages can provide scalability when dealing with multiple format sizes.
  • Pixels: This option is useful for targeting a fixed resolution (e.g., 1920 x 1080 for full HD), or if you’re specifically setting a value in pixels (e.g., a 5-pixel Padding boundary).
  • Initial: This sets the property back to its default state (Unity’s own default styling rules), ignoring the current styling values.

To apply a scaling rule to the entire UI at the same time, UI Toolkit offers settings similar to those in Unity UI. They are available in the Panel Settings.

More resources

In our 130+ page e-book, User interface design and implementation in Unity, designed for artists, designers, and developers, you can find tips and best practices for building sophisticated interfaces with Unity’s two UI systems, Unity UI and UI Toolkit. Plus, get a walkthrough of the companion demo UI Toolkit sample - Dragon Crashers.

Other helpful resources:

We hope you enjoyed this article! Thanks for reading, and let us know if you have any feedback about the articles or the sample project so far.