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 = ClickEvent.GetPooled())
    {
        evt.target = target;
        target.SendEvent(evt);
    }
}

// A handler that only wants the capture phase, and stops the event there.
void RegisterCaptureOnlyHandler(VisualElement el)
{
    el.RegisterCallback<PointerDownEvent>(evt =>
    {
        if (evt.propagationPhase == PropagationPhase.TrickleDown)
        {
            evt.StopPropagation(); // no descendant/bubble handler will see it
        }
    }, TrickleDown.TrickleDown);
}

Common Mistakes

Quick Reference

Advanced Notes

Layout/style recalculation cost. UI Toolkit's layout engine is Yoga (flexbox); any change to a property that affects box geometry (size, padding, margin, flex properties, adding/removing/reordering children) invalidates layout for the affected subtree and triggers a re-solve on the next update, while style-only changes (color, opacity below the point of triggering a new stacking context) are cheaper repaint-only invalidations. Manual/UIE-performance-consideration-runtime.html frames the practical rule: batch structural changes (build a subtree off-tree, then Add() it once) rather than mutating the live tree element-by-element in a loop, and prefer updating existing elements' values over destroying/recreating them for per-frame or per-tick UI (health bars, score counters). usageHints (ScriptReference/UIElements.VisualElement-usageHints.html) exists specifically to tell the renderer an element will move/transform every frame so it can put that element on its own rendering path and avoid regenerating geometry for the whole batch each time — apply it to elements animated continuously (a dragged icon, a pulsing indicator), not globally, since it has its own memory/state overhead.

Editor-window vs runtime usage differ more than the shared API suggests. The same VisualElement/UXML/USS code compiles and mostly behaves identically whether hosted in an EditorWindow's root or a runtime UIDocument, but three things diverge: (1) theming — the Editor supplies an implicit default theme for built-in controls, while a runtime panel renders those controls with no chrome at all unless PanelSettings.themeStyleSheet is explicitly assigned; (2) input routing — Editor UI receives input through the Editor's own event pump, while runtime UI depends on PanelSettings plus whichever input backend (legacy Input Manager or Input System package) is active, per Manual/UIE-Runtime-Event-System.html; (3) IPanel.contextType (ScriptReference/UIElements.IPanel-contextType.html) reports ContextType.Editor vs ContextType.Player, which is the correct branch point for any shared code that must behave differently in the two hosts (e.g. skipping Editor-only Inspector fields like PropertyField/ObjectField at runtime). Always verify a runtime panel in Play Mode or an actual build — the UI Builder canvas preview approximates runtime appearance but doesn't guarantee it, especially for anything theme-dependent.

The two binding systems are not layered on each other. The runtime binding system (Binding/DataBinding/dataSource) was added well after the legacy SerializedObject-oriented BindableElement system and is a parallel implementation, not a superset — code written against one doesn't automatically benefit from features of the other (e.g. BindingLogLevel diagnostics apply to the runtime system, not to SerializedObject binding failures, which surface differently). When a project needs both an Inspector/Editor tool and a runtime UI screen for conceptually "the same" data, expect to write two separate binding wire-ups rather than sharing one.