Unity UI Toolkit Runtime

Unity UI Toolkit Runtime API

This skill is the deep-dive into UI Toolkit's C# UnityEngine.UIElements runtime surface: custom controls, manipulators, event handling, data binding, and scripted style/query access. It deliberately does not cover UXML/USS authoring basics, UI Builder, or the UI Toolkit-vs-uGUI decision — see unity-ui for those. Assume the reader already has a UIDocument showing UXML content and wants to know how to drive, extend, and manipulate it from code.

Retrieval Sources

All paths below were verified with find/ls against /media/artiq/FRESH_DRIVE/Books/Unity6/Documentation/en/ on this pass. The local ScriptReference/UIElements.* namespace alone contains 3,535 pages (one per member, not per class), so this table is a curated set of the load-bearing types/members for runtime scripting, not an exhaustive index — use find ScriptReference -iname "UIElements.<ClassName>*" to pull every member page for a class this table names.

That is 103 verified rows spanning the visual tree, event/manipulator system, both binding systems (legacy Editor SerializedObject binding and the newer runtime data-binding system), custom-control authoring, runtime style scripting, and UIDocument/PanelSettings runtime hosting.

Key Guidelines

VisualElement Tree Basics & Querying

Every node in a UI Toolkit tree — panels, containers, and built-in controls alike — is a VisualElement (ScriptReference/UIElements.VisualElement.html). Structural mutation goes through Add/Insert/Remove/RemoveAt/Clear, which by default target the element's contentContainer (ScriptReference/UIElements.VisualElement-contentContainer.html) rather than the element itself — a composite control (e.g. one with a header plus a body) commonly overrides contentContainer to redirect Add() into an inner child, and hierarchy.Add (via the VisualElement.Hierarchy struct, ScriptReference/UIElements.VisualElement.Hierarchy.html) is the escape hatch that bypasses that redirection when you need to add directly to the true root. Once attached, panel (ScriptReference/UIElements.VisualElement-panel.html) is non-null and worldBound/localBound become meaningful; treat panel == null as "not yet part of a live tree" and gate any panel-dependent logic on AttachToPanelEvent/DetachFromPanelEvent.

Finding elements uses two APIs layered on UQueryState<T> (ScriptReference/UIElements.UQueryState_1.html): the shorthand element.Q<T>(name, className) for "give me the first match," and the fluent element.Query<T>().Class("foo").Where(...) builder (UQueryBuilder<T>, ScriptReference/UIElements.UQueryBuilder_1.html) for multi-match filtering, ending in .ToList()/.ForEach(...)/.Build(). .Build() compiles the query into a reusable UQueryState<T> you can re-run cheaply — build it once (e.g. in a field) rather than re-parsing the query string every call.

using UnityEngine.UIElements;

public class InventoryPanelController
{
    readonly VisualElement root;
    readonly UQueryState<VisualElement> slotQuery;

    public InventoryPanelController(VisualElement root)
    {
        this.root = root;
        // Compile once; re-run cheaply every time inventory state changes.
        slotQuery = root.Query<VisualElement>(className: "inventory-slot").Build();
    }

    public void RefreshHighlights(int selectedIndex)
    {
        int i = 0;
        slotQuery.ForEach(slot =>
        {
            slot.EnableInClassList("inventory-slot--selected", i == selectedIndex);
            i++;
        });
    }

    // Single-match lookup by name — the common case for wiring up one specific control.
    public Button FindConfirmButton() => root.Q<Button>("confirm-btn");
}

Building Custom Controls ([UxmlElement]/[UxmlAttribute])

A custom control is a VisualElement subclass that composes built-in elements (or draws its own content) and exposes state as C# properties. Manual/UIE-create-custom-controls.html documents the modern pattern: mark the class partial and attach [UxmlElement] (ScriptReference/UIElements.UxmlElementAttribute.html), which triggers a source generator that emits the UXML-factory boilerplate (VisualElement.UxmlSerializedData, ScriptReference/UIElements.VisualElement.UxmlSerializedData.html) so the control becomes usable as a UXML tag and shows up in UI Builder's library. Any property meant to be settable from UXML gets [UxmlAttribute] (ScriptReference/UIElements.UxmlAttributeAttribute.html); primitive types (int/float/string/enum/Color) work directly, while complex types need the patterns in Manual/ui-systems/custom-control-attributes-complex-data-types.html. The older UxmlFactory<T,U>/UxmlTraits pattern (ScriptReference/UIElements.UxmlFactory_2.html, ScriptReference/UIElements.UxmlTraits.html) still works and is sometimes still necessary for attribute types the generator doesn't support — Manual/ui-systems/migrate-custom-control.html maps one pattern to the other.

using UnityEngine;
using UnityEngine.UIElements;

[UxmlElement]
public partial class HealthBar : VisualElement
{
    static readonly string ussFillClass = "health-bar__fill";

    readonly VisualElement fill;
    float value = 1f;

    [UxmlAttribute]
    public float Value
    {
        get => value;
        set
        {
            this.value = Mathf.Clamp01(value);
            fill.style.width = new Length(this.value * 100f, LengthUnit.Percent);
        }
    }

    [UxmlAttribute]
    public Color FillColor
    {
        get => fill.resolvedStyle.backgroundColor;
        set => fill.style.backgroundColor = value;
    }

    // Parameterless constructor is required — UI Builder/UXML instantiates via it.
    public HealthBar()
    {
        AddToClassList("health-bar");
        style.height = 18;
        style.backgroundColor = new StyleColor(new Color(0.15f, 0.15f, 0.15f));

        fill = new VisualElement();
        fill.AddToClassList(ussFillClass);
        fill.style.height = new Length(100, LengthUnit.Percent);
        fill.style.backgroundColor = new StyleColor(Color.red);
        hierarchy.Add(fill); // bypass any future contentContainer override

        Value = 1f;
    }
}

// Usage in UXML once compiled: <HealthBar value="0.75" fill-color="#22CC22" />

Manipulators & Pointer Events

A Manipulator (ScriptReference/UIElements.Manipulator.html) packages reusable pointer/gesture behavior as an object attached to a target via target.AddManipulator(...) (VisualElementExtensions.AddManipulator, ScriptReference/UIElements.VisualElementExtensions.AddManipulator.html) instead of hand-registering callbacks inline. Manual/UIE-manipulators.html frames this as composition: a control can carry several independent manipulators (drag + context-menu + hover-highlight) without any of them knowing about each other. Subclass PointerManipulator (ScriptReference/UIElements.PointerManipulator.html, unifies mouse/touch/pen) or the older MouseManipulator (ScriptReference/UIElements.MouseManipulator.html, mouse-only, uses ManipulatorActivationFilter for button/modifier gating) and implement the paired RegisterCallbacksOnTarget/UnregisterCallbacksFromTarget (ScriptReference/UIElements.Manipulator.RegisterCallbacksOnTarget.html) — these are called automatically when the manipulator is added/removed, and every callback registered in one must be unregistered in the other or the target leaks a handler when the manipulator is removed.

RegisterCallback<T> (on CallbackEventHandler, ScriptReference/UIElements.CallbackEventHandler.html) takes an optional TrickleDown phase argument (ScriptReference/UIElements.TrickleDown.html): the default TrickleDown.NoTrickleDown registers for the bubble-up phase (event travels leaf→root), while TrickleDown.TrickleDown registers for the capture phase (root→leaf, fires first). A drag manipulator typically wants PointerDownEvent in TrickleDown so it sees the press before any child stops propagation, then calls target.CapturePointer(evt.pointerId) (PointerCaptureHelper, ScriptReference/UIElements.PointerCaptureHelper.html) so subsequent PointerMoveEvents keep arriving even if the pointer leaves the element's bounds — essential for drag-to-resize/reorder UI, per Manual/UIE-Capture-Events.html.

using UnityEngine;
using UnityEngine.UIElements;

/// Drags `target` freely within its parent using absolute positioning.
public class DragManipulator : PointerManipulator
{
    Vector2 startPointerPos;
    Vector2 startElementPos;
    bool dragging;

    public DragManipulator(VisualElement target) => this.target = target;

    protected override void RegisterCallbacksOnTarget()
    {
        target.RegisterCallback<PointerDownEvent>(OnPointerDown);
        target.RegisterCallback<PointerMoveEvent>(OnPointerMove);
        target.RegisterCallback<PointerUpEvent>(OnPointerUp);
    }

    protected override void UnregisterCallbacksFromTarget()
    {
        target.UnregisterCallback<PointerDownEvent>(OnPointerDown);
        target.UnregisterCallback<PointerMoveEvent>(OnPointerMove);
        target.UnregisterCallback<PointerUpEvent>(OnPointerUp);
    }

    void OnPointerDown(PointerDownEvent evt)
    {
        if (evt.button != 0) return;
        dragging = true;
        startPointerPos = evt.position;
        startElementPos = new Vector2(target.resolvedStyle.left, target.resolvedStyle.top);
        target.CapturePointer(evt.pointerId);
        evt.StopPropagation();
    }

    void OnPointerMove(PointerMoveEvent evt)
    {
        if (!dragging || !target.HasPointerCapture(evt.pointerId)) return;
        Vector2 delta = (Vector2)evt.position - startPointerPos;
        target.style.left = startElementPos.x + delta.x;
        target.style.top = startElementPos.y + delta.y;
    }

    void OnPointerUp(PointerUpEvent evt)
    {
        if (!dragging) return;
        dragging = false;
        target.ReleasePointer(evt.pointerId);
    }
}

// usage: myPanel.AddManipulator(new DragManipulator(myPanel));

Data Binding

UI Toolkit has two distinct binding systems and the docs are explicit that they don't interoperate (Manual/UIE-data-binding.html). The legacy Editor binding system connects BindableElements (ScriptReference/UIElements.BindableElement.html) to a SerializedObject/SerializedProperty via bindingPath and BindingExtensions.Bind/BindProperty (ScriptReference/UIElements.BindingExtensions.html) — this only works inside the Editor (custom Inspectors, EditorWindow), documented at Manual/UIE-editor-binding.html. The runtime binding system (Manual/UIE-runtime-binding.html, Manual/UIE-get-started-runtime-binding.html) is general-purpose and works in builds: any plain C# object can be a data source, its bindable properties are exposed with [CreateProperty] (from Unity.Properties, consumed by the binding system), and a VisualElement is connected to a source path via dataSource/dataSourcePath (ScriptReference/UIElements.VisualElement-dataSource.html) plus either a UXML binding markup block or a scripted SetBinding(bindingId, new DataBinding { ... }) call (ScriptReference/UIElements.VisualElement.SetBinding.html). BindingMode (ScriptReference/UIElements.BindingMode.html) controls direction: ToTarget (source→UI, one-way live), ToTargetOnce (source→UI, snapshot), ToSource (UI→source), TwoWay. A data source that wants to push live updates (not just be polled) implements INotifyBindablePropertyChanged (ScriptReference/UIElements.INotifyBindablePropertyChanged.html) and raises property-changed notifications; per Manual/UIE-runtime-binding-define-data-source.html this is what makes ToTarget/TwoWay bindings refresh without a manual poll loop.

using Unity.Properties;
using UnityEngine.UIElements;

// Plain C# data source — no MonoBehaviour/ScriptableObject required.
public class PlayerStats : INotifyBindablePropertyChanged
{
    public event EventHandler<BindablePropertyChangedEventArgs> propertyChanged;

    int health = 100;
    [CreateProperty]
    public int Health
    {
        get => health;
        set
        {
            if (health == value) return;
            health = value;
            propertyChanged?.Invoke(this, new BindablePropertyChangedEventArgs(nameof(Health)));
        }
    }
}

public class StatsPanelController
{
    public StatsPanelController(VisualElement root, PlayerStats stats)
    {
        root.dataSource = stats;

        var healthLabel = root.Q<Label>("health-label");
        healthLabel.SetBinding("text", new DataBinding
        {
            dataSourcePath = new PropertyPath(nameof(PlayerStats.Health)),
            bindingMode = BindingMode.ToTarget,
        });
    }
}

For lists, bind a ListView's itemsSource to a runtime collection (Manual/UIE-bind-to-list.html) rather than manually instantiating one element per item — ListView/MultiColumnListView (ScriptReference/UIElements.ListView.html, ScriptReference/UIElements.MultiColumnListView.html) virtualize rows, recycling a small pool of visual elements regardless of collection size. If a binding silently does nothing, raise BindingLogLevel (ScriptReference/UIElements.BindingLogLevel.html, Manual/UIE-runtime-binding-logging-levels.html) via Binding.SetPanelLogLevel/Binding.SetGlobalLogLevel before assuming the data source is wrong — most "binding doesn't update" bugs are a missing [CreateProperty], a PropertyPath typo, or a BindingMode that doesn't include the direction you need, and the log level surfaces exactly which.

Runtime Style Manipulation

VisualElement.style (ScriptReference/UIElements.VisualElement-style.html, typed as IStyle, ScriptReference/UIElements.IStyle.html) is the writable inline-style surface — every USS property has a same-named C# property here (style.width, style.flexDirection, style.backgroundColor, ...), and assigning to it is equivalent to an inline style="..." attribute: it wins over any USS selector regardless of specificity. Each property's value type wraps the raw value with a StyleKeyword (StyleLength, StyleColor, StyleEnum<T>, etc., e.g. ScriptReference/UIElements.StyleLength.html) so you can express StyleKeyword.Null (fall through to USS), Auto, None, or Initial in addition to a concrete value — assigning a raw value like style.width = 100 implicitly wraps it as a concrete StyleLength, but clearing an inline override requires explicitly assigning StyleKeyword.Null, not just leaving it unset. resolvedStyle (IResolvedStyle, ScriptReference/UIElements.IResolvedStyle.html) is the read-only opposite: the final cascaded/computed value after USS + inline + layout, useful for reading "what size did this actually end up" after a layout pass, but never assignable.

Custom USS properties (--my-highlight-color: red;) aren't exposed on IStyle/IResolvedStyle at all — read them via customStyle.TryGetValue (ICustomStyle/CustomStyleProperty<T>, ScriptReference/UIElements.ICustomStyle.html) inside a CustomStyleResolvedEvent handler, which is how a custom control lets USS/UI Builder theme it without hardcoding colors in C#, per Manual/UIE-create-custom-style-custom-control.html.

using UnityEngine;
using UnityEngine.UIElements;

public class ThemedPanel : VisualElement
{
    static readonly CustomStyleProperty<Color> highlightColorProp = new("--highlight-color");
    Color highlightColor = Color.yellow; // fallback if USS doesn't define it

    public ThemedPanel()
    {
        RegisterCallback<CustomStyleResolvedEvent>(OnCustomStyleResolved);
    }

    void OnCustomStyleResolved(CustomStyleResolvedEvent evt)
    {
        if (customStyle.TryGetValue(highlightColorProp, out Color color))
            highlightColor = color;
    }

    public void Highlight(bool on)
    {
        // StyleKeyword.Null clears any inline override and falls back to USS/default.
        style.borderBottomColor = on
            ? new StyleColor(highlightColor)
            : new StyleColor(StyleKeyword.Null);
    }
}

UIDocument & PanelSettings

UIDocument (ScriptReference/UIElements.UIDocument.html) is the MonoBehaviour that hosts a visual tree in a scene: it exposes rootVisualElement (the entry point for all Q/Add calls), takes a visualTreeAsset (VisualTreeAsset.CloneTree(), ScriptReference/UIElements.VisualTreeAsset.html, is what actually instantiates the UXML into live elements under the root), and references a PanelSettings asset (ScriptReference/UIElements.PanelSettings.html) that owns everything about how that panel renders: scaleMode (ScriptReference/UIElements.PanelSettings-scaleMode.html — Constant Pixel Size / Scale With Screen Size / Constant Physical Size, the runtime analogue of uGUI's CanvasScaler), referenceResolution, sortingOrder (multiple UIDocuments can share one PanelSettings and layer via this), and targetTexture (redirect the panel into a RenderTexture instead of the screen, the basis for world-space UI Toolkit panels per unity-ui's coverage). Multiple UIDocuments can also nest via parentUI, letting one panel's tree host another as a subtree rather than each owning an independent root. Manual/UIE-create-panel.html and Manual/UIE-Runtime-Panel-Settings.html walk the full setup; critically, a runtime panel needs PanelSettings.themeStyleSheet assigned or built-in controls (Button, Toggle, etc.) render with zero default chrome — there is no implicit Editor theme at runtime.

using UnityEngine;
using UnityEngine.UIElements;

[RequireComponent(typeof(UIDocument))]
public class MainMenuController : MonoBehaviour
{
    [SerializeField] VisualTreeAsset menuAsset;

    void OnEnable()
    {
        var doc = GetComponent<UIDocument>();
        VisualElement root = doc.rootVisualElement;
        root.Clear();
        menuAsset.CloneTree(root);

        root.Q<Button>("start-btn").clicked += OnStartClicked;
        root.Q<Button>("quit-btn").clicked += () => Application.Quit();
    }

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

Event System (bubbling/trickling)

Every UI Toolkit event dispatch walks the tree in two phases (Manual/UIE-Events.html, Manual/UIE-Events-Dispatching.html): TrickleDown (capture), root-to-target, then BubbleUp (default), target-to-root. PropagationPhase (ScriptReference/UIElements.PropagationPhase.html) tells a handler which phase it's currently in (AtTarget when currentTarget == target). evt.StopPropagation() halts further phase traversal (a common footgun: it does not automatically prevent the event's default action — call evt.PreventDefault() separately if that's also needed, e.g. suppressing a click's default behavior while still consuming the event). EventInterestAttribute (ScriptReference/UIElements.EventInterestAttribute.html) lets a custom VisualElement declare up front which event categories it actually handles, letting the dispatcher skip it entirely for irrelevant events — worth adding to custom controls that sit deep in large trees since dispatch cost is paid per-ancestor per-event regardless of whether any callback is registered. Events can also be synthesized for tests or simulated input, per Manual/UIE-Events-Synthesizing.html, by pulling a pooled instance and sending it directly.

using UnityEngine.UIElements;

// Programmatically simulate a click for a UI test, bypassing real input.
void SimulateClick(VisualElement target)
{
    using (var evt = ClickEve

…(truncated)