Getting started with UI toolkit

1. What is UI Toolkit?

Let’s take a minute to understand the components that make up the UI Toolkit tech stack.

UI Toolkit is a collection of assets, tools, and systems.

• UI Assets: Think of UI Assets as the UI building blocks. These assets consist of Unity XML (UXML) and Unity Style Sheet (USS) files. UXML files represent the content and structure of your UI, similar to markup languages like HTML and XML.
  
  USS files are inspired by Cascading Style Sheets (CSS), which are used to define the appearance and style of your content. You’ll use both of these asset types in this tutorial.

• UI Tools: To speed up your UI workflows, UI Toolkit comes with a number of tools. These include the UI Builder, which is an editor that makes it easy to build your UI from visual building blocks rather than code. You can, however, still create both your UXML and USS content through code, or you can use a mix of the two depending on your preferences. The second most important tool in UI Toolkit is the UI Debugger, which is used to test and identify issues.
  

• UI Systems: UI Systems are a collection of tools that makes it easy for you to handle events, rendering, styles, and layout.

2. What you’ll create

In this tutorial, you’ll build a simple main menu. The image below is a reference image that shows what the finished main menu will look like.

You’ll use assets from the Dragon Crashers UI Toolkit project, which is a much more comprehensive demo of what you can do in UI Toolkit, and we highly recommend you check it out after completing this tutorial.

3. Set up a new project

To begin learning how to use UI Toolkit, follow these instructions:

1. Open the Unity Hub and select New Project.

2. From the Editor Version dropdown, select the most up to date version of Unity 6 (6000.0.x.x).

3. Select the Universal 2D template (URP).

4. Name your project “UTK main menu” .

5. From the Unity Organization dropdown, select the Unity Organization you want to use for the workspace.

6. Disable the Connect to Unity Cloud checkbox.

7. Select Create project.

The Unity Editor will automatically open and begin loading your new project.

To start building your UI, you’ll need to download the DGUITK Unity package, which contains everything you’ll need to complete this tutorial.

8. In the Project window, right click in the Assets folder and select Import Package > Custom Package...

9. Locate the package and select Open.

The import prompt should look something like this.

All assets should now be available in the DragonCrashersAssets folder.

4. Setting up our UI Document

To render the UI in your scene, you’ll need a GameObject with a UI document component added to it.

A UI Document is responsible for holding a reference to your UI Toolkit building blocks (UI elements) so that it’s rendered in the Game view. You can think of this as the equivalent of the Canvas used in uGUI. Like the Canvas, a UI document is also used to define some parameters of how the game should render.

To set up a UI Document, follow these instructions:

1. Right click in the Hierarchy window and select UI Toolkit > UI Document.

2. In the Project window, right click the DragonCrashersAssets folder and select Create > UI Toolkit > UI Document to create a UI Document file (.UXML file).

3. Rename the new UI Document file “MainMenu”.

4. Double click the MainMenu file to open it in the UI Builder window.

The UI Builder window consists of several smaller windows. Let’s quickly take a look at what those are.

1. StyleSheets window: StyleSheets define a set of layout and formatting rules for your UI elements. You can use the StyleSheets window to manage StyleSheets and their styling rules, known as USS Selectors,enabling you to share styles across multiple UI Documents (UXML) and elements.

1. Hierarchy window: This window lists all the VisualElements in your UI. VisualElements are the base building blocks of UI, like GameObjects are for your scenes.

1. Library window: This window contains prefabricated elements you can use to build your UI by simply dragging and dropping them into the Hierarchy window.

1. Viewport window: This window is a view of what the UI will look like, shown on a square called the Canvas. The Canvas can be resized and panned.

1. Code Previews window: This window shows you the code that is created in both the UI Document (UXML) and the StyleSheets (USS) every time you add an element to your UI.

1. Inspector window: This window works similarly to the Inspector window for GameObjects in the Editor: it displays properties for the currently selected VisualElement.

Code Previews window: This window shows you the code that is created in both the UI Document (UXML) and the StyleSheets (USS) every time you add an element to your UI . Inspector window: This window works similarly to the Inspector window for GameObjects in the Editor: it displays properties for the currently selected VisualElement.

5. Create your first UI elements

There are many possible design approaches to creating UI. The planning, processes, and implementation increase in complexity with responsive design because there are multiple target device resolutions and as well as devices that work in both portrait and landscape mode. To keep things simple, you’ll create a UI with a fixed layout for just one resolution with Full HD (1920 x 1080px).

Now let's create the first UI elements. From the reference image, you can see that you need one text label and three buttons.

1. In the Library window, select the Standard button, then, under the Controls section, select and drag a Label element and three Button elements into the Hierarchy window.

Note: To save your work, select File > Save or press Ctrl+S (macOS: Cmd+S).

Your UI Builder Hierarchy window should look like the image below.

Don't worry about the buttons stretched across the full width of the screen; you’ll fix that later.

Now let’s update the Inspector values of the new Label element to reflect our design.

2. Select the Label element in the Hierarchy window and rename it “headline__label”.

Note: We use the double underscore (__) in order to follow the Block Element Modifier (BEM) naming convention. This improves readability, maintainability, and consistency in your code. For more details on BEM naming rules, check out this guide.

3. In the Hierarchy window, select the Label element. In the Inspector window, use the foldout (triangle) to expand the Attributes section, locate the Text property, and enter “MAIN MENU” in the box.

4. Use the foldout (triangle) to expand the Text section. Select the Font picker (⊙) and select ChelaOne-Regular.ttf.

Note: Normally you’d have to generate your own font asset first, but we’ve provided them for you so you can focus on UI creation.

5. Set the Size property to “55px”.

6. Select the Color property box and set the Color to white and the Alpha property to “255”.

Note: The white marker to the left of the property name indicates that changes from the default settings have been made, which makes it easier for you to track your changes.

Let’s add some shadows so the text stands out more.

7. Use the foldout (triangle) to expand the Shadow section, select the Color property box, set the Color to black and the Alpha property to 255. Then set both the Offset Horizontal and Vertical properties to 2px.

Next let’s set up the three buttons by adding unique names and values.

9. In the Hierarchy window, select the first button element. In the Inspector window, select the Button box and enter “start-game__button”. Use the foldout (triangle) to expand the Attributes section, locate the Text property, and enter “START GAME” in the box.

10. Repeat the above step for the second and third button, but enter “credits__button” in the Button box and “CREDITS” in the Text property box for the second button and “about-us__button” in the Button box and “ABOUT US” in the Text property box for the third button.

Notice how the UI Builder view immediately updates as we save the changes. .

11. Save your changes by selecting File > Save or pressing Ctrl+S (macOS: Cmd+S).

Let’s take a look at how the UI will look so far.

First you’ll need to configure the UI Builder Viewport window setting so it's representative of what the game will look like on the target device.

11. In the Viewport window, open the Preview theme menu and select the Unity Default Runtime theme.

12. In the Hierarchy window, select the MainMenu.uxml. In the Inspector window, under the Canvas Size section, set the Size Width property to 1920 and the Size Height property to 1080 to match the target resolution of 1920 x 1080.

13. In the Viewport window, select the Fit viewport button to display the UI using the updated Canvas Size settings.

Your UI should now be rendered properly! However, the buttons are stretched across the full width of the screen. We’ll fix that shortly.

With your first UI elements ready and the UI Builder set up, let's check how it renders in the Game view.

14. Exit the UI Builder window and go to the Game view.

15. In the Hierarchy window, select the UIDocument GameObject, then in the Inspector window, under the UI Document component, select the Source Asset picker (⊙) and select the MainMenu UXML file.

The UI should now show up in the Game view.

6. Configure your UI elements

Now that your basic UI shows up in the Game view, let’s configure the Panel settings file to alter how the UI elements are rendered in the game, including scaling across different resolutions. You need to do this to ensure that the UI behaves consistently across different devices and resolutions.

1. In the Project window, go to Assets > UI > Panel Settings and select the Panel Settings asset to open it in the Inspector window.

2. Open the Scale Mode dropdown and select Scale With Screen Size.

3. Set the Reference Resolution to X = 1920 and Y = 1080.

If you now change the display to Full HD in the Game view of the Editor, it renders consistently with the screen size.

When you created the label, we briefly touched on how, when creating UI, it’s common practice to reuse the same elements again and again. Doing this means that you’ll need formatting rules that can be easily applied across multiple instances of the same element. In some projects, you might have the same styled button in more than 100 places. Instead of having to configure each use of the same buttons manually, you can define a style rule for the button once that's then applied across all instances of that button. In other words, you can define the styling for your button once rather than setting it up individually.

Let's use a USS to define the styling rules for the button once and then propagate those changes to every instance of the same button.

4. In the UI Builder window, open the Add (+) dropdown in the upper-left corner of the StyleSheets window, then select Create New USS.

5. Name the new StyleSheet “MainMenuStyleSheet” and save it in the same folder as your existing project files.

It’s not uncommon to have multiple StyleSheets in a project, and it’s often the case to have one for each complex screen rather than having one giant StyleSheet to accommodate for all styles in the game.

Now let’s define some rules for how we want the buttons to look to match your design and use the artwork we provided. To do this, you’ll use a styling rule called a selector. Selectors provide various types including Elements, Classes, and ID selectors for different purposes, giving you complete control over the styling.

Note: For this use case, you’ll use a class selector, but Unity Style Sheet (USS) files offer a wide range of selector options for more advanced use cases.

6. In the StyleSheets window, right-click the MainMenuStyleSheet, select Add selector, and name it “.menuRegularButton”.

The “.” indicates it's a class as opposed to an element, and because we’re defining a USS class, the general practice is to keep it in camelCase. While less relevant for this one screen menu, the point of using a naming convention is so that, in a larger game your codebase scales nicely.

Note: Remember to save your work by selecting File > Save or pressing Ctrl+S (macOS: Cmd+S).

Now let’s define the look of the button in your new class.

7. In the StyleSheets window, select the .menuRegularButton selector.

8. In the Inspector window, use the foldout (triangle) to expand the Text section, select the Font picker (⊙), and select ChelaOne-regular.ttf. Set the Size property to 41, then select the Color property box, set the Color to white and the Alpha property to 255.

9. Use the foldout (triangle) to expand the Shadow section, select the Color property box, set the Color to black and the Alpha property to 255. Then set both the Offset Horizontal and Vertical properties to 2px.

None of the changes you’ve made will be visible at this point because you haven’t instructed any of the buttons to use the updated class styling. To do this, you’ll need to assign the new class to the visual elements you want it to be applied to.

10. From the StyleSheets window, drag the .menuRegularButton selector into the start-game, credits, and about-us buttons in the Hierarchy window.

Note: If your button elements don’t have the yellow text that shows the classes they use, select the More (⋮) menu in the upper-right corner of the Hierarchy window and select Class List.

All the buttons should now be updated to show the new font settings!

Let's change the look of the button even more by adding a background sprite.

11. In the StyleSheets window, select the .menuRegularButton selector. In the Inspector window, use the foldout (triangle) to expand the Background section, open the Image property’s Background image dropdown, and select Sprite. Select the Image picker (⊙) and select UI_atlas_70-yellow-button.

All buttons will now have a yellow background sprite!

12. Use the foldout (triangle) to expand the Border section and set the Width and Radius properties 0px.

13. Select File > Save or press Ctrl+S (macOS: Cmd+S) to save your changes.

Right now the buttons are stretched 100% across the screen. As you can see in the reference image below, they should be 312px x 93px. Let’s scale the buttons to a proper fixed size.

14. Use the foldout (triangle) to expand the Size section and set the Width to 312px and the Height to 93px.

Now let’s give each button a specific colour so they really stand out. You’ll achieve this using inline styles. Inline styling refers to applying styles directly to a VisualElement using the style property, instead of using USS. This is useful because inline styles have a higher specificity over classes.

15. In the Hierarchy window, select the Credits button element. In the Inspector window, use the foldout (triangle) to expand the Inlined Styles > Background section, select the Image picker (⊙), and select UI_atlas_99-blue-button.

16. In the Hierarchy window, select the About us button element. In the Inspector window, use the foldout (triangle) to expand the Inlined Styles > Background section, select the Image picker (⊙), and select UI_atlas_104-red-button.

Your buttons should now look something like this:

7. Add a background image and logo

Next, let’s add a cool background to your menu. You want the background image to cover the entire screen and have the other elements of the UI rendered on top of it. The original format of the background image is 2048x1024, so you also need to scale it properly without distorting the proportions of the image.

1. Select the Visual Element element from the Library window, under the Container section, and drag it into the Hierarchy window.

Visual Elements are the basic building blocks of UIs, similar to an empty GameObject in the Unity Editor.

2. Rename the VisualElement element “panel-container”.

3. In the Hierarchy window, select the #headline-label, #start-game_button, #credits_button, and #about-us_button elements and drag them into the panel-container.

This makes the label and button elements child elements of the new panel-container element, establishing an organizational hierarchy of how your styling will be applied.

4. In the Hierarchy window, select the panel-container element. In the Inspector window, use the foldout to expand the Inlined Styles > Background section, select the Image picker (⊙), and select HomeScreenBackground.png.

5. Ensure the Size Width and Height properties are set to 100% so the image fills the entire screen.

You might have noticed that the image is now somewhat distorted. That’s because the image resolution is not optimized for full HD.

6. Set the Scale Mode property to scale-and-crop.

This crops the image to fill the entire screen while preserving its aspect ratio, thus avoiding distortion.

Finally, let’s add the Dragon Crasher logo to the menu.

8. Following the same procedure as when you created the container panel, drag in a visual element into the Hierarchy window and name it “logo”.

9. Select the logo element, and in the Inspector window, use the foldout (triangle) to expand the Background section, select the Image picker (⊙) and select UI_atlas_115-logo.

10. Use the foldout (triangle) to expand the Size section and set the Width property to 567px and the Height property to 292px.

8. Align your UI

You now have all the elements you need for a functional UI, but you still need to align them properly. You could set each of them up individually, but it’s much more efficient to create a panel that holds all of your elements.

1. Select the Visual Element element from the Library window, under the Container section, and drag it into the Hierarchy window.

2. Rename it “center-panel” and make it a child element of the panel-container element. Move the buttons and label so they are nested as child elements of the center-panel element.

You can now apply layout rules to the center panel that will affect all of its child elements.

Now let’s create a second class in your USS to define the styling of the center panel so you don’t have to apply inline styling to each separate element.

6. In the upper-left corner of the UI Builder window, right click the MainMenuStyleSheet file and select Add selector…

7. Name the new selector “.centerPanel”.

8. In the StyleSheets window, select the .centerPanel class. In the Inspector window, use the foldout (triangle) to expand the Size section and set the Size Width property to 567px and the Size Height property to 100%.

To make the changes take effect, you need to apply the .centerPanel class to the center-panel element. Luckily, Visual Elements can have multiple classes.

9. Open your MainMenu.uxml file in your IDE and add the “centerPanel” class name to the existing class parameter for the center-panel element to make the element use both.

Now let’s align your elements properly. UI Toolkit offers a number of configuration options that we explain in more detail in our UI Toolkit: Introduction and Flexbox Layout article.

10. In the UI Builder window, select the center-panel element, and in the Inspector window, use the foldout (triangle) to expand the Align section.

11. Set the Align Items property to value: center.

This will make all the child elements of the center-panel element align nicely in the center of the panel.

12. Set the Justify Content property to value: center.

This will center the content around the main axis (in this case the vertical axis.)

13. Set the Align Self property to value: center.

This will align the center-panel element and all of its child elements to the center of the screen.

Let’s remove the .debugClass as we no longer need it.

14. Select the center-panel element and, in the Inspector window, use the foldout to expand the Style Class List section, then select the x to the right of the class name.

The UI should now look something like this:

The centering worked nicely, but some more space around the buttons and moving the logo closer to the top of the screen would make things even better. Because you’re working with a fixed layout for a fixed resolution, you can use margins to accomplish both of these things. UI Toolkit uses the box model to define both margin and padding values.

Let’s start by adding some margin to the menuRegularButton class.

15. In the StyleSheets window, select the menuRegularButton class. In the Inspector window, use the foldout (triangle) to expand the Spacing section. Set the Margin property to 5px

Now let’s add a specific bottom margin for the About us button in order to push the content slightly higher up.

16. In the Hierarchy window, select the #about-us_button element. In the Inspector window, use the foldout (triangle) to expand the Spacing > Margin section and set the Bottom property to 50px.

As you can see, the styling from the class has been applied. However, you can override these settings in order to have a higher specificity and thus overrule the class styling.

Because you set the center-panel element to justify the content value to the center, adding the margin of 50px will cause the centering of the content around the main axis (in this case the vertical axis) to push the logo up slightly.

Finally, let’s use transitions and pseudo classes to add another level of interactivity to the button elements when users engage with them. Transitions and pseudo classes are both types of variants of classes you can use to apply special styling based on their state or position.

Let’s create a cool effect for when the buttons are moused over that gives the user a subtle visual feedback effect.

17. In the upper-left corner of the StyleSheets window, right click the MainMenuStyleSheet file and select Add selector.

18. Name the new selector “.menuRegularButton:hover”.

Once created, you'll notice the :hover color coding indicating it's a pseudo class.

19. In the StyleSheets window, select the .menuRegularButton:hover class. In the Inspector window use the foldout (triangle) to expand the Transform section and set the Scale X and Y properties to 1.05.

20. Use the foldout (triangle) to expand the Transition Animations section and set the Duration property to a value between 0.1 and 0.5.

21. Select the Preview button in the upper-left corner of the Viewport window to simulate what this functionality looks like at runtime.

You now know the basics of UI Toolkit! You’ve created a simple game menu with functioning buttons, a background image, logo, and it all scales appropriately to your target screen resolution.

If you’d like to learn more about UI Toolkit, make sure to check out our tutorial projects like QuizU and the Dragon Crashers UI toolkit sample as well as our free ebook to continue your learning journey.