Get started with UI Builder

Understand the workflow to create UI in UI Builder by an example.

Read time 7 minutes

Last updated 24 days ago

Want to learn how to create UI with UI Builder? Use this example to get started.

To create UI in the UI Builder:

Create a new UI Document (UXML).
Add elements to create your UI hierarchy.
Set up attributes and style properties in the Inspector.
When more than one element starts to need the same style properties, create USS style sheets and selectors.
Test your UI and if you are satisfied with the results, extract inline style properties to USS classes.
Save the UI Document (UXML).

Prerequisites

Before you start, get familiar with the following:

Example overview

This example creates the main view for the Create a list view runtime UI example. It creates a root element as the background, with two containers. One container holds the character name list and another holds the character details. In the character details container, you add background and foreground frames. Finally, you add two labels for the character name. This example won't create the character name list entry UI.

Create the root element

Create a new project and then create a root visual element that covers the entire screen. Set your root element to have a background color and center all child elements in the middle of the screen.

Create a project in Unity with any template.
Select Window > UI Toolkit > UI Builder.
In the UI Builder window, at the top left of the
Viewport
?
window, select File > New to create a new UXML document.

UI Builder file menu
Name it as
```
MainView.uxml
```
and save.
Drag VisualElement from Library into the Hierarchy panel.

Create new elements by dragging from the Library

Tip
You can also double-click a control to add it to the Hierarchy panel.
Select the element from the Hierarchy panel.
In the
Inspector
?
panel, make sure Flex > Grow is
```
1
```
. This sets the
```
flex-grow
```
property to
```
1
```
, making it cover the entire screen.
Set the Flex property
To center all child elements, set both Align Items and Justify Content to
```
Center
```
.
Center children
Set Background > Color to
```
#732526
```
.
Note
By default, the Alpha value for colors is
0
, making them fully transparent. To make color opaque, set the Alpha value to
255
.
Root element background color

Create the parent container

Create a new VisualElement underneath the root element. This element becomes the parent container for the left and right sections of the UI.

Drag VisualElement from Library to the root VisualElement in the Hierarchy panel.

Add a child VisualElement
Select the element from the Hierarchy panel.
In the Inspector panel, set Flex > Direction to
```
row
```
.
Set Flex > Grow to
```
0
```
.
Set Size > Height to
```
350
```
pixels.
Center container properties

Create the character names list container

Add a ListView as the child element of the container to hold the character names.

Drag a ListView from the Library to the container VisualElement in the Hierarchy panel.
Select the element from the Hierarchy panel.
In the Inspector panel, set Name to
```
CharacterList
```
.
Background container with the empty element inside
Set Size > Width to
```
230
```
pixels.
Set Spacing > Margin > Right to
```
6
```
pixels.
Size and Margin foldouts for the character list
Set Background > Color to
```
#6E3925
```
.
Set Border > Color to
```
#311A11
```
.
Set Border > Width to
```
4
```
pixels.
Set Border > Radius to
```
15
```
pixels.
Styled character list

Create the character details container

Add a new VisualElement under the same parent as the

#CharacterList

to hold the character details container. The purpose is that when the user selects a character from the list on the left, it displays the character's portrait, name, and class.

Drag a VisualElement from the Library to the container element in the Hierarchy panel. This is the container to hold all the elements on the right.
Select the element from the Hierarchy panel.
In the Inspector panel, set Align > Align Items to
```
flex-end
```
.
Set Align > Justify Content to
```
space-between
```
.
Justify content property
Add another VisualElement as the child of the right container.
Select the element from the Hierarchy panel.
Set Flex > Grow to
```
0
```
.
Set Size > Width to
```
276
```
pixels.
In the Align section, set both Align Items and Justify Content to
```
center
```
.
Set Spacing > Padding to
```
8
```
pixels.
Properties of the character details container
Set Background > Color to
```
#AA5939
```
.

Create a USS class for the border style

The character details container will use the same border styles as the character names list container. Create a USS class to apply to both containers.

In the StyleSheet panel, select + > Create New USS.
Name it
```
MainView.uss
```
and select Save.
Click in the Add new selector... field and enter
```
.border
```
. A .border
selector appears in the StyleSheet panel.
In the StyleSheet panel, select .border
.
In the Inspector panel, set Border > Color to
```
#311A11
```
.
Set Border > Width to
```
4
```
pixels.
Set Border > Radius to
```
15
```
pixels.
Drag .border
from the StyleSheet panel to the character details container VisualElement.
Drag .border
from the StyleSheet panel to # CharacterList.
Select # CharacterList.
In the Inspector panel, right-click Border and select Unset to remove the inline style you set earlier.

Your UI layout now looks like the following:

Create the character portrait background

Add the individual UI controls to the character details container. The first step is to add the character portrait background.

Drag VisualElement from Library to the character details container.
Select the element from the Hierarchy panel.
In the Size section, set both Width and Height to
```
120
```
pixels.
Set Spacing > Padding to
```
4
```
pixels.
Set Background > Color to
```
#FF8554
```
.
Set Border > Color to
```
#311A11
```
.
Set Border > Width to
```
2
```
pixels.
Set Border > Radius to
```
13
```
pixels.
Background frame for the character portrait

Create the character portrait foreground

Next in the character details container, add the foreground for an actual image.

Drag VisualElement from Library to the character details container.
Select the element from the Hierarchy panel.
Set Name to
```
CharacterPortrait
```
.
Set Flex > Grow to
```
1
```
, so that the image can use all the available space.
Set Background > Scale Mode to
```
scale-to-fit
```
, so that you can scale the image to match the element size while keeping the correct aspect ratio.
VisualElement for the portrait image

Create labels

Add two label controls to the character details container to display the selected character's name and class.

Drag Label from Library to the character details container in the Hierarchy panel.
Set
```
Name
```
to
```
CharacterName
```
.
Drag Label from Library to the character details container in the Hierarchy panel.
Set
```
Name
```
to
```
CharacterClass
```
.
Add labels for name and class
Select the
```
#CharacterName
```
element.
Set Text > Font Style to
```
B
```
.
Set Text > Size to
```
18
```
pixels.
Change font settings
In the Viewport window, select File > Save to save the changes to
```
MainView.uxml
```
.

Extract inline styles

In UI Builder, you can create elements and use inline styles only to experiment while the number of elements is still small. As you build a more complex UI, it's easier to manage styles using style sheets. You can extract inline styles to a style sheet in UI Builder.

Select the root visual element.
In the Inspector panel, in the Style Class List field, enter
```
.background
```
as the class name.
Select Extract Inlined Styles to New Class. This creates a
```
.background
```
class selector with the inline styles you set for the root element and updates the UI Document (UXML) for the root visual element to use the class selector instead of the inline styles.
Extract inline styles to a new class
In the Viewport window, select File > Save.

If you want to continue to work on the Create a list view runtime UI example, you can repeat the steps to extract styles for all the other elements, and follow the instructions to create the example.

Additional resources

Style elements with UI Builder

Documentation

Development

User Acquisition

Monetization

Industry

Unity Engine

User Manual

Script Reference