Is UI Toolkit ready for production?

At the time of writing this article (April 2023), UI Toolkit has been out for a while. Time to evaluate if it can be used in any upcoming projects.

The short answer is: not yet but it may be in Unity 2024. If you want to know why then read on.

Source: Unity's UI Toolkit Demo

UI Toolkit compared to CSS

UI Toolkit uses the layout principles of a layout engine called Yoga created by Facebook [1]. Yoga only implements a subset of Flexbox.

There still are some very basic CSS features missing. You can find the full list of supported properties on the USS Properties website.

Data Source: [8]

Noteworthy examples of missing CSS features:

z-index: This is an important feature for things like tabs and popups. [2]
text-transform: You can not even make text upper or lower case. [3]
box-shadow: Adding shadows is a key part of making any UI. [4] Though there are open-source implementations [5]

UI Toolkit compared to UGUI

UI Toolkit does not support custom materials and hence custom shaders. For business apps the default shader might be enough but for games, people will need a bit more freedom with how their UI is presented.

Things like text animation are not possible and may only become possible if Unity decides to make the text vertices accessible. If you look at what TextMeshPro and other assets have done with text vertices then it should be clear that hiding them is stifling creativity. Unity Quote [7]:

To provide a more cohesive integration with UITK, we would like to allow users to leverage the existing USS and transform properties to achieve those animations. Hence why we are not exposing the text vertices as TMP does.

Since UI Toolkit ditched the GameObject hierarchy only very few of the assets in the Asset Store will work with UI Toolkit.

Things that need to improve

Text & Fonts

Compared to the feature set of TextMeshPro UI Toolkit still has some way to go. The text formatting features are limited at the moment. These need to improve a lot to become comparable to what we have with TextMeshPro.

Data Binding

As of now, there is no data binding for runtime (it exists for the Editor). It is coming to the runtime too but it is not yet here.

Localization

Unity's own localization solution is currently stuck since they are waiting for data binding support to be added to the runtime. [9]

UI Builder

The UI Builder feels sluggish and the UX is lacking. For example, one can not edit multiple elements at once.

Another example: If you have a typo in your class name then you will have to remove that class (click), select the input field (click), type in the whole class name again (you can't copy it), and then click again to add it. That's just poor UX.

Editor Scripting (adding custom inspectors) has been a hallmark of Unity. The UI Builder offers nothing in that regard. The bare minimum would be the ability to add custom attributes via code and edit them in the UIBuilder.

Standard Components

Unity's premade UI components need to improve. They do not properly support controllers and some older versions have problems with scroll views. Things like popups and drop-downs are sometimes displayed outside the visible screen area.

Asset Store Support

There aren't many UI Toolkit assets in the Asset store yet. Though that probably is a chicken and egg problem. The more people will use UI Toolkit the more asset will be created.

It is a big hurdle since there are so many UI assets made for UGUI. Once UI Toolkit is in full swing it will be a mess. Some assets will only support UGUI, others only UI Toolkit. We have seen it happen before with the render pipelines (Built-In vs URP & HDRP).

UI Toolkit Framework critique

Visual Tree

UI Elements throws away the scene hierarchy approach. Any UI is now inside a black-box UIDocument component which is just a link to an internal hierarchy called the visual tree. That tree can be built via code or from a .uxml file via the UIBuilder window.

This has far-reaching implications. Pretty much every pre-existing UI Asset in the Asset Store is based on UGUI components (GameObjects and MonoBehaviours). Users could add them to a game object and there they would do their thing.

With UI Toolkit this is no longer possible. Unity should provide a similar mechanism in UI Toolkit. Data binding will not solve this as that's only about data, not functionality. There needs to be an easy way to attach additional logic to elements. Custom components fulfill that role but there is a problem.

Custom components use inheritance instead of composition and that's why they are a dead-end for UI customization. They can not be extended without generating an unmaintainable mess of sub-classes, see "Composition vs Inheritance".

The current implementation of the VisualTree constantly throws away the generated UI element objects. Whenever a change is made the objects are recreated. This is okay from an architectural standpoint. It gives you a clean state every time something has changed. However, if you try to maintain a link to a visual element it is cumbersome. One can re-query the elements or place a proxy in the visual tree to fetch them but it remains a tricky business. However. The desired approach according to Unity is, quote [6]:

The intended pattern is that you have a MonoBehaviour that requires UIDocument and that itself exposes all required UI control to the rest of your game while keeping its VisualElement references private.

The funny thing is, these VisualElement references are breaking all the time due to the visual tree reloading. One has to listen for attach and detach events to keep up with them. We need a way to get a nice (persistent) lock on the currently attach UI Element.

Assets Recommendations

I hope you liked the article. Here are some assets we'd like to recommend. If you buy one of them then we will receive some money which helps fund this project.

Disclosure: This text may contain affiliate links, which means we may receive a commission if you click a link and purchase something that we have recommended. While clicking these links won't cost you any money, they will help fund this project! The links are created by Unity and Partnerize (Unity's affiliate partner).

UI Toolkit FAQs

Can I use a custom shader on UI Elements?

No, but maybe it will be added in Unity 2024 [10]

Can I mix UGUI with UIToolkit?

You can use Canvases and UI Documents at the same time but you can not use one within the other.

If you want to position some elements within a UI Element based on anchors then set the position attribute to "absolute" and you will be able to arrange it much like in the UGUI anchor system.

Does the UI Toolkit support Controller Input?

Partially. Some things work, others don't (drop downs).

Can I access the UI vertices to make custom effects?

Partially. You can add vertices to the shapes but text vertices can not be changed.

Is it worth switching from a UGUI project to UIElements?

You may have difficulties since UI Toolkit does not yet support all features that UGUI does. Also, there are still numerous bugs in UIToolkit.

Can I extend the UI Builder like the default inspector?

No, but maybe in the future custom attributes can be edited in the UI Builder [11].

When will the data binding be done?

Probably within the Unity 2023 cycle, or maybe Unity 2024. Roadmap

When will the localization be done?

Probably within the Unity 2023 cycle, or maybe Unity 2024. Roadmap

Sources

UI Toolkit Manual on Layouting https://docs.unity3d.com/Manual/UIE-LayoutEngine.html
z-index forum thread: https://forum.unity.com/threads/z-index-support.736781/
USS Property Reference: https://docs.unity3d.com/Manual/UIE-USS-Properties-Reference.html
box-shadow forum thread: https://forum.unity.com/threads/box-shadow-property.1020940/
UIToolkit box shadow implementation: https://gist.github.com/tattyd/6807d6be9e550a1f24ad17f21d69177e, https://forum.unity.com/threads/soft-shadows-my-custom-component.1300653/
"The intended pattern is that you have a MonoBehaviour that requires UIDocument and that itself exposes all required UI control to the rest of your game while keeping its VisualElement references private." - Unity forum: https://forum.unity.com/threads/does-uidocument-clear-contents-when-disabled.1097659/#post-7071439
"To provide a more cohesive integration with UITK, we would like to allow users to leverage the existing USS and transform properties to achieve those animations. Hence why we are not exposing the text vertices as TMP does." Unity forum: https://forum.unity.com/threads/interacting-with-subsections-of-text.1317933/#post-8350119
Number of CSS properties, (we took an average), https://css-tricks.com/how-many-css-properties-are-there/
"The work is still ongoing with an estimate of landing during the 2023 cycle. We are currently waiting for the UI Toolkit binding improvements to land, once that is completed then we need to apply some changes to the package." Unity Forum Jan 2023, https://forum.unity.com/threads/localization-for-ui-toolkit.881890/#post-8701245
"We'll resume work on gaming (vs authoring) use cases in the 2024 release cycle. World-space rendering, compositing, custom shaders, and ...", Unity Forum: https://forum.unity.com/threads/when-will-ui-toolkit-have-feature-and-performance-parity-with-ugui.1327947/#post-8392725
"Aiming for 2023 LTS, but that's not a guarantee at this point.", Unity Forum, https://forum.unity.com/threads/custom-ui-builder-attribute-fields.945491/#post-8876868