Search Unity

UIElements is a new retained mode UI framework for Unity, available now as a public API for Unity 2019.1. In its current form, it’s a tool that makes it easier for you to extend the Unity Editor. In-game support and visual authoring will come in future releases.

Traditionally, building custom Editor windows and inspectors in Unity meant using IMGUI, an immediate mode API. IMGUI makes it easy to start building user interfaces but fails to scale when you’re building more complex applications. It’s also difficult for the system to optimize rendering because the user can drastically change the structure of the UI at any time within the current frame. Lastly, all UI is declared in C# which means that any future tool for authoring UI visually would need to generate C# code, which is a complicated proposition.

In UIElements, as a retained mode API, the idea is that you build your UI hierarchy of objects and let the system render it for you. This way, the system can optimize what it draws, and when it draws, leading to better overall performance. This paradigm also lets you decouple your hierarchy and styling from functionality, which results in a better separation of concerns and more approachable UI authoring for both artists and programmers.

Retained Mode

The basic building block of UIElements is the VisualElement class. All elements are either a VisualElement or inherit from it. Individual VisualElements can be parented to each other to form your UI hierarchy. Layouting, styling, and other systems then traverse this hierarchy to properly render your UI to screen.

In the Editor, each EditorWindow has a rootVisualElement property which represents the top VisualElement of your hierarchy. Elements need to be added as children to this root in order for the system to know about them and draw them.

As long as the element is in the hierarchy, it will continue to draw, update, and consume user events, without input from the developer. This is where retained mode differs from immediate mode the most. The developer only needs to declare what should happen, and when, but doesn’t need to manage the frame-to-frame rendering.

To stop drawing an element, like this slider, you can either make it temporarily invisible with a styling change or remove it permanently from the hierarchy.

Retained mode also allows for a document model that lets you separate your hierarchy (using UXML) and styling (USS) declarations into separate assets. In C#, you can focus on just binding your declared UI with functionality and data using the built-in query system and event system.

With separate assets for hierarchy and styling, authoring UI visually becomes a possibility. This will make it easier for all users to tweak, author, and design UI in Unity.

Reusable Templates (UXML)

You can assemble your hierarchy of elements entirely in C#. However, just like styles, most of your hierarchy won’t change very much throughout the lifetime of your UI. Therefore, we recommend that you modularize your UI by defining your hierarchy in a separate XML-based asset called UXML.

Tag names correspond to C# types, with full support for user-defined types inheriting from VisualElement. Attributes will be set on the new elements on creation, and nested tags will become children of their parent tag.

You can load this .uxml asset like any other Unity asset, constructing a VisualTreeAsset object in the process. You can then instantiate (or clone) this VisualTreeAsset under any element and as many times as you wish.

Getting to the elements that we just created via UXML is done via the query system described shortly below.

Shared Styles (USS)

Styles can be set directly on VisualElements via properties in C#. However, since most styles are statically defined, it makes sense to separate their descriptions from the UI logic in C#. UIElements uses Unity-specific StyleSheet assets, called USS, which uses a subset of the CSS standard. You can use the same selectors familiar from CSS to identify which elements should get which styles, while the styles themselves are key-value pairs.

You can load this .uss asset like any other Unity asset, constructing a StyleSheet object in the process. You can then assign it to your desired element and it will automatically apply the styles within to this element, as well as all its children. If children are added afterward, the styles will be applied to them as well.

While styles can be applied by name attribute or by C# type, for better style reuse you can also assign your elements one (or more) style classes and match your styles in USS by these classes. You can think of them as tags.

You can also add multiple StyleSheets to the same element and have multiple rules matching the same element. Use USS to setup complex overriding rules while reusing styles as much as possible. Iterating on shared styles, like the color of your generic button, becomes trivial — especially since you no longer have to wait for C# to recompile. StyleSheet (USS) asset changes are automatically applied in the Editor on file save.


The query system in UIElements is called UQuery. It’s similar to its web counterpart jQuery in that it lets you find elements in your hierarchy using a combination of their name attribute, currently assigned style class list, and C# type.

You can also build a Query object for optimized reuse where you need to run a query many times on a dynamic hierarchy.


UIElements comes with an event system. Events are usually sent to specific elements and then propagate down and up the UI tree until they are consumed, but this propagation behavior is customizable. Basic events, like MouseMoveEvent, are sent by the system and you can register to receive. You can also define and send your own custom user events.

Events are the main way for you to know when a state in the UI has changed or the user has performed an action. In the example below, we detect when the user has changed the slider value and display this new value in the label element.


If your UI appears broken, or if you simply don’t see elements that should be on screen, the UIElements Debugger will be your friend. It will feel familiar to those that have used the website debuggers in Chrome and Firefox.

To debug an element in your UI with this debugger, you can enable Pick and hover over it or you can right-click on it and select Inspect. The debugger displays the full live hierarchy of the current window on the left pane and a styles inspector on the right pane. In this styles inspector, you can look at what styles are assigned to an element and where each style value is coming from (ie. which StyleSheet asset and which selector). Finally, you can live append and edit style values and see their effects in your UI.

Other Features

  • Bindings: Many controls can be bound to SerializedObjects to link the UI with your asset data. Any element implementing the IBindable interface (like all our built-in fields) can accept a string binding path to a SerializedProperty. You can then explicitly Bind() your element hierarchy to SerializedObjects.
  • IMGUIContainer: If you have a lot of existing Editor UI written in IMGUI, you can use the special IMGUIContainer element to embed IMGUI UI within a UIElements UI as just another element. The IMGUIContainer takes a callback that serves as your OnGUI() loop, receiving all the events from outside as it normally would.
  • Scheduler: UIElements comes with a simple built-in scheduler. You can use the scheduler to delay a callback a set amount of time, and/or executed it repeatedly at a set interval.

Future Releases

We’re actively working on supporting use of UIElements for in-game UI. In addition, we plan to have a visual workflow around UIElements to enable people to design and build functional UI with little or no C# coding.

In the meantime, more and more of Unity itself will be built using UIElements, including Inspectors, new tools using dedicated Editor windows, and toolbars.

We will continue to maintain, and in some cases improve, IMGUI and uGUI and we have no plans for obsolescence in the foreseeable future. That said, UIElements will become the recommended and most supported way to build UI in Unity, starting with the Unity Editor in Unity 2019.1.

How do I get started?

The Unite LA 2018 talk on UIElements is a good place to start. It comes with a sample project that you can use to follow along, highlights the main differences and equivalences between IMGUI and UIElements, and covers most of UIElements’ main features in a functional example-driven way.

You can download the example project from GitHub.

For more in-depth information on the API, see Unity 2019.1 Manual.

49 replies on “What’s new with UIElements in 2019.1”

I would really like to have a visual editor for this where I can design the UI by simply placing components on an artboard without having to code the layout.

Great work, I wonder what are the reason you decided to build a new xml, css and javascript implementations instead of using html css and js allowing us to use existing frameworks?

Also I would love a hint on when will this be possible for in game UI

Amazing progress but in my opinion the Unity team should focus on getting this system working for in-game UI as soon as possible. Since the game we’re working on is quite UI heavy we have been trying all sorts of approaches to make our UI development easier. We’re currently using the Chromium Embedded Framework that has been implemented into our game with all sorts of hackery just so we’re able to have the modularity and ease of development we needed. This UIElements system changes all that and makes our CEF implementation obsolete. No more compute heave Chromium running in front of our game. Please please please make this a priority for the sake of not just my team of developers but for all Unity developers that struggle with the current UI system.

«In its current form, it’s a tool that makes it easier for you to extend the Unity Editor.»
Sorry, but I can’t see how this could be true. Node based declaration (UXML) is the worst solution when iterating a UI, a use case where IMGUI can’t be beat. And style sheets are at best a time-wasting toy for real production tools.
I can’t see another usage than for in-game UI. But then what about the UnityEngine.UI stuff ?

I’m really excited about this. I am hoping to build a node-based editor tool and I’d love to get my hands on the GUI code for the Shader Graph or even a demo class for node-based interfaces using UIElements.

@Ashkan — Take a look at Noesis. It’s a XAML runtime for Unity. It is pretty much WPF but it works in Unity3D and it works *amazingly* well.

Will UIElements support SVG files, without the SVG importer?

Thinking icons, and other graphical assets you want to have in your UI.

There’s a bug in your documentation for Retained Mode.

IntSlider slider = new IntSlider();

should be:

SliderInt slider = new SliderInt();

What wpf features are you missing, exactly?
Awkward styling?
Obscure binding semantics?
Ugly dependency/attached properties declaration?
Tons of generated back code?

Noesis ( has a drop-in XAML with close to the full feature set for Unity..

If you use a XAML user control for a unit tile in user interface, a mod or DLC can copy the XAML file and add features to it — and so it’s a lot more flexible. Data Triggers, in particular, can be awesome for mods and DLC = and can be combined with Storyboards.

Looking forward to authoring systems as a blend of this and IMGUI. Seemingly a very nice case of both worlds bestness.

Gotta love how so many developers love to bash on web development, and yet more and more of native desktop applications are steering towards similar paradigms to that of web development.

Web development sucks because it’s a chaotic wasteland of lawlessness and non-standardized practices. Take paradigms made common in web development and apply them to other disciplines and they suddenly become bearable to use.

Awesome. This looks like the silver bullet, but also sounds like having 3 different systems for UI may end up being a hard to solve puzzle… some will have to let go sooner rather than later…
On a side note, I was wondering if recent controls like Treeview will be ported to this new system?

Just wow. What year is this, I feel like I have gone back in time to 2006. Im terrified of this new paradigm and how branched it is from ugui and ecs.

Comments are closed.