Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท UI and Input

UI Toolkit in Unity

Learn Unity UI Toolkit - UXML layouts, USS styles, the UIDocument component, querying elements and callbacks - and when to choose it over uGUI, with runnable stand-ins.

UI Toolkit is Unity's second UI system. Instead of game objects on a Canvas, it uses ideas from the web: a document tree written in UXML (like HTML), styles written in USS (like CSS) and a flexbox-style layout engine. It started as the system for editor windows and is a full runtime option in Unity 6.

If you know HTML and CSS, much of this will feel familiar; see CSS Flexbox for the layout model it borrows. This lesson shows the three files involved, how to wire them from C#, and how to decide between UI Toolkit and the uGUI system from the first two lessons of this chapter. Unity is not available here, so the C# you can run is a stand-in for the layout and query logic.

The three pieces

  1. UXML describes the structure.
  2. USS describes the look.
  3. C# finds elements and reacts to events.

A UXML file MainMenu.uxml:

XML
<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <Style src="MainMenu.uss" />
    <ui:VisualElement name="root" class="screen">
        <ui:Label text="Space Miner" class="title" />
        <ui:Button name="play-button" text="Play" class="menu-button" />
        <ui:Slider name="volume" label="Volume" low-value="0" high-value="1" value="0.8" />
        <ui:Toggle name="fullscreen" label="Fullscreen" />
    </ui:VisualElement>
</ui:UXML>

And MainMenu.uss:

CSS
.screen {
    flex-grow: 1;
    align-items: center;
    justify-content: center;
    background-color: rgb(18, 24, 48);
}
.title {
    font-size: 48px;
    color: white;
    margin-bottom: 24px;
}
.menu-button {
    width: 240px;
    height: 56px;
    border-radius: 12px;
}
.menu-button:hover {
    background-color: rgb(70, 110, 220);
}

USS supports class selectors, name selectors (#play-button), pseudo-classes (:hover, :active, :disabled) and USS variables. Only a subset of CSS exists, and some property names differ (-unity-font-style, -unity-text-align). Layout is flexbox only, and the default flex-direction is column.

Showing it in the game

Add an empty game object with a UI Document component, assign the UXML as Source Asset and a Panel Settings asset (the counterpart of the Canvas Scaler: scale mode, reference resolution, sort order). Then write a script:

C#
using UnityEngine;
using UnityEngine.UIElements;

[RequireComponent(typeof(UIDocument))]
public class MainMenuController : MonoBehaviour
{
    Button playButton;
    Slider volume;

    void OnEnable()
    {
        VisualElement root = GetComponent<UIDocument>().rootVisualElement;

        playButton = root.Q<Button>("play-button");
        volume = root.Q<Slider>("volume");

        playButton.clicked += OnPlay;
        volume.RegisterValueChangedCallback(evt => AudioListener.volume = evt.newValue);
    }

    void OnDisable()
    {
        playButton.clicked -= OnPlay;
    }

    void OnPlay() => Debug.Log("Starting the game");
}

Q<T>(name, className) looks up the first matching element and Query<T>() returns all of them. Do the lookups in OnEnable, because the visual tree is rebuilt whenever the UIDocument is enabled. Element-specific events are registered with RegisterCallback<ClickEvent>(...), RegisterValueChangedCallback, and so on, using the same bubbling idea as the web DOM.

Querying the tree

Searching a visual tree is a depth-first walk. The runnable stand-in below builds a tiny tree and implements Q by name and by class, so you can see why a name must be unique and why a typo returns null.

C# Stand-in: a visual tree and Q()

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Flexbox in one picture

UI Toolkit lays children out along a main axis. flex-direction: row puts them side by side, justify-content spaces them along the axis and align-items aligns them across it. flex-grow lets an element take the remaining space. The stand-in splits a row between fixed and growing children, which is the heart of the algorithm.

C# Stand-in: flex-grow distribution

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

UI Toolkit or uGUI?

Choose UI Toolkit for screen-space menus, HUDs and settings, for tools and editor extensions, and when you want designers to work in a UI Builder with reusable styles. Choose uGUI when the UI must live in the 3D world (World Space canvases), needs per-element shaders and animation through the Animator, or when your team and assets already depend on it. Unity 6 adds world-space UI Toolkit support and data binding (dataSource, DataBinding), but uGUI still has the larger ecosystem of ready-made packages. Many projects use UI Toolkit for menus and uGUI for floating damage numbers.

Common mistakes

  • Querying elements in Awake or Start, before the document is ready, and getting null.
  • Forgetting a Panel Settings asset, so nothing renders.
  • Writing CSS properties USS does not know; they are ignored with a console warning.
  • Expecting display: block or float layout; there is only flexbox and absolute positioning.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does UXML describe?

    UXML is the markup (like HTML); USS carries the styling.
  2. 2. Which layout model does UI Toolkit use?

    Layout is flexbox, with optional absolute positioning for individual elements.
  3. 3. Where is the best place to query elements with root.Q<T>()?

    The visual tree is created when the UIDocument is enabled, so queries belong in OnEnable.
  4. 4. A World Space canvas with a particle shader on a button fits which system best?

    uGUI elements are game objects and work with materials, shaders and the Animator in the scene.

Summary

  • UI Toolkit = UXML (structure) + USS (styles) + C# (behavior), with flexbox layout.
  • A UIDocument plus Panel Settings puts a UXML tree on the screen.
  • Use Q<T>("name") and Query<T>() in OnEnable; register callbacks and unregister them.
  • Choose UI Toolkit for menus and tools, uGUI for world-space and animated, shader-heavy UI.

Next: The Animator Controller