Unity UI

Retrieval Sources

All paths below were verified with find/ls against /media/artiq/FRESH_DRIVE/Books/Unity6/Documentation/en/ on this pass. Confirmed gap, re-checked and still true: the local ScriptReference/ has no API pages for the uGUI package's UnityEngine.UI namespace — EventSystem, CanvasScaler, GraphicRaycaster, Selectable, Button, Image, Text, ScrollRect, Toggle, etc. do not exist anywhere under ScriptReference/ (checked both an EventSystem*.html glob and a UI.*.html glob at the ScriptReference root — zero hits for either). Only UnityEngine.UIModule.html (the built-in, non-package UI module) is present, and it covers exactly seven types: Canvas, CanvasGroup, CanvasRenderer, RectTransform/RectTransformUtility, RenderMode, AdditionalCanvasShaderChannels, StandaloneRenderResize. For uGUI component APIs (Button, Selectable, EventSystem, etc.), state plainly that local docs don't cover them and fall back to general knowledge, flagging it as unverified against local sources.

That is 56 verified rows — well past the 12-20 target — spanning UI Toolkit fundamentals, UXML/USS authoring, UI Builder, the runtime event system, world-space UI, custom controls/manipulators, performance, and the uGUI Canvas/RectTransform surface that does exist locally.

Key Guidelines

UI Toolkit vs uGUI Decision

UI Toolkit is Unity's modern retained-mode UI system: a browser-like model with a visual tree (UXML), a CSS subset for styling (USS), and a Yoga-based flexbox layout engine (Manual/UIE-LayoutEngine.html). It decouples structure, style, and behavior into separate files/languages the way web front-ends do. uGUI (Manual/com.unity.ugui.html) is the older GameObject-based system: every element is a GameObject with a RectTransform plus Components (Image, Button, Text, etc.), styled and behaviorally scripted directly on those Components/MonoBehaviours, and arranged live in the Game View. Per Manual/UI-system-compare.html, prefer UI Toolkit for complex editor tooling, data-heavy runtime UI (lists, dynamic dashboards), and anywhere draw-call/layout-rebuild cost matters at scale; prefer uGUI where the asset-store/prefab ecosystem, designer-driven Inspector-only workflows, or existing project conventions dominate. They are not mutually exclusive within one project — a game can render its HUD in uGUI while using UI Toolkit for a settings/inventory screen — but avoid mixing them for the same screen since input routing, layout math, and asset pipelines don't share state.

Decision checklist (Manual/UI-system-compare.html):
- Editor tooling / custom inspectors / EditorWindow        -> UI Toolkit (only supported path)
- Runtime UI with large dynamic lists/data binding          -> UI Toolkit (ListView, data binding)
- Runtime UI needing 3rd-party asset-store components fast  -> uGUI
- World-space diegetic UI (health bars in 3D space)          -> uGUI is simpler; UI Toolkit needs
                                                                 a RenderTexture-backed world panel
                                                                 (Manual/ui-systems/world-space-ui.html)
- Team is designers who work entirely in the Inspector       -> uGUI

UXML/USS Authoring

UXML is XML that declares the visual tree's structure (which elements exist and how they nest); USS is a CSS subset that declares appearance (Manual/UIE-UXML.html, Manual/UIE-USS.html). A VisualTreeAsset (the compiled UXML) is instantiated at runtime or loaded by a UIDocument; USS files are attached either in UXML via <Style src="..."> or in code via visualElement.styleSheets.Add(...). Selectors support type (Button), class (.my-class), name (#my-name), descendant (space), direct child (>), and pseudo-classes (:hover, :checked) — see Manual/UIE-USS-Selectors.html. Every built-in control has its own UXML reference page under Manual/UIE-uxml-element-*.html (e.g. UIE-uxml-element-Button.html, UIE-uxml-element-ListView.html) listing that element's specific attributes.

<!-- UXML: MainMenu.uxml -->
<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <Style src="MainMenu.uss" />
    <ui:VisualElement name="root" class="menu-root">
        <ui:Label text="Settings" class="menu-title" />
        <ui:Button name="start-btn" text="Start Game" class="menu-button" />
        <ui:Button name="quit-btn" text="Quit" class="menu-button menu-button--danger" />
    </ui:VisualElement>
</ui:UXML>

/* USS: MainMenu.uss */
.menu-root {
    flex-direction: column;
    align-items: center;
    padding: 24px;
}
.menu-button {
    width: 200px;
    height: 40px;
    margin-top: 8px;
}
.menu-button:hover {
    scale: 1.05 1.05;
}
.menu-button--danger {
    background-color: rgb(180, 40, 40);
}

// C#: load the compiled UXML and wire up behavior
[SerializeField] VisualTreeAsset menuAsset; // assign MainMenu.uxml in Inspector
void OnEnable()
{
    var root = GetComponent<UIDocument>().rootVisualElement;
    root.Clear();
    menuAsset.CloneTree(root);
    root.Q<Button>("start-btn").clicked += () => Debug.Log("Start pressed");
}

Canvas & RectTransform (uGUI)

Every uGUI element sits on a RectTransform (ScriptReference/RectTransform.html), a 2D specialization of Transform that stores anchorMin, anchorMax, anchoredPosition, sizeDelta, pivot, and offsetMin/offsetMax instead of raw world position/scale. A Canvas (ScriptReference/Canvas.html) is the root render surface; its renderMode (ScriptReference/RenderMode.html) picks the render path — Screen Space - Overlay draws directly to the screen with no camera; Screen Space - Camera renders through an assigned camera at a fixed plane distance (Canvas.planeDistance); World Space treats the Canvas as an ordinary 3D object with a RectTransform sized in world units, usable for diegetic/VR UI. CanvasRenderer (ScriptReference/CanvasRenderer.html) is the low-level mesh renderer every Graphic uses internally — rarely touched directly. CanvasGroup (ScriptReference/CanvasGroup.html) lets you fade (alpha), disable interaction (interactable), and block/allow raycasts (blocksRaycasts) for an entire subtree in one component, which is the standard way to implement fade-in/out panels or temporarily-disabled UI without touching every child.

using UnityEngine;

// Fully stretch a RectTransform to fill its parent, then inset by 20px on all sides.
void FillParentWithMargin(RectTransform rt, float margin = 20f)
{
    rt.anchorMin = Vector2.zero;   // bottom-left of parent
    rt.anchorMax = Vector2.one;    // top-right of parent
    rt.pivot = new Vector2(0.5f, 0.5f);
    rt.offsetMin = new Vector2(margin, margin);   // left/bottom inset
    rt.offsetMax = new Vector2(-margin, -margin); // right/top inset
}

// Fade a panel out and stop it from blocking raycasts, via CanvasGroup.
IEnumerator FadeOut(CanvasGroup group, float duration)
{
    float t = 0f;
    group.interactable = false;
    while (t < duration)
    {
        t += Time.deltaTime;
        group.alpha = Mathf.Lerp(1f, 0f, t / duration);
        yield return null;
    }
    group.blocksRaycasts = false;
}

Responsive Layout / Anchoring

In uGUI, anchors (not raw position) define responsive behavior: anchorMin/anchorMax are normalized (0-1) points on the parent rect that the element's corners lock to. When anchorMin == anchorMax (a "point anchor"), the element has a fixed size and anchoredPosition is the offset from that anchor point — it does not resize when the parent does. When anchorMin != anchorMax (a "stretch anchor", e.g. min (0,0) max (1,1)), the element's edges track the parent's edges and it resizes with the parent; in this mode offsetMin/offsetMax (exposed in the Inspector as Left/Bottom/Right/Top) become the inset from those edges rather than a size. RectTransformUtility (ScriptReference/RectTransformUtility.html) provides the screen-to-local conversions (ScreenPointToLocalPointInRectangle, WorldToScreenPoint) needed for custom input handling, drag-and-drop, or converting a world-space marker into 2D HUD position. In UI Toolkit, responsive layout instead comes from flexbox (flex-grow, flex-shrink, align-items, justify-content in USS) plus the PanelSettings scale mode (Manual/UIE-Runtime-Panel-Settings.html) — Constant Pixel Size, Scale With Screen Size (with a reference resolution and width/height match slider), or Constant Physical Size, directly analogous to uGUI's CanvasScaler modes.

using UnityEngine;

// Convert a fixed-size RectTransform to a top-right-anchored HUD element
// that keeps a constant 16px margin regardless of parent resize.
void AnchorTopRight(RectTransform rt, Vector2 size, float margin = 16f)
{
    rt.anchorMin = new Vector2(1f, 1f);
    rt.anchorMax = new Vector2(1f, 1f);
    rt.pivot = new Vector2(1f, 1f);
    rt.sizeDelta = size;
    rt.anchoredPosition = new Vector2(-margin, -margin);
}

Runtime Event System

uGUI needs exactly one EventSystem in the scene to route input (pointer/gamepad/keyboard) to Selectables such as Button; a GraphicRaycaster on each interactive Canvas determines which Graphic a pointer hit. Local docs do not cover these types' APIs (see Retrieval Sources note) — this paragraph is drawn from general Unity knowledge, not the local ScriptReference. UI Toolkit's runtime input model is different and better documented locally: Manual/UIE-Runtime-Event-System.html describes how the active input backend (legacy Input Manager or the Input System package) is translated into UI Toolkit's own event classes (PointerDownEvent, ClickEvent, NavigationMoveEvent, etc., enumerated in Manual/UIE-Events-Reference.html) and dispatched through the visual tree in two phases — TrickleDown (root-to-target) then BubbleUp (target-to-root), per Manual/UIE-Events.html. Each UIDocument's PanelSettings asset is the runtime-panel equivalent of a Canvas+EventSystem pairing — it owns sort order, scaling, and (indirectly, via the shared input backend) how input reaches that panel. Register handlers with RegisterCallback<T> on any VisualElement, or attach a reusable Manipulator (Manual/UIE-manipulators.html) such as PointerManipulator-derived drag logic instead of hand-rolling callback registration on every element.

using UnityEngine;
using UnityEngine.UIElements;

public class DragHandle : PointerManipulator
{
    public DragHandle(VisualElement target) { this.target = target; }

    protected override void RegisterCallbacksOnTarget()
    {
        target.RegisterCallback<PointerDownEvent>(OnPointerDown, TrickleDown.TrickleDown);
        target.RegisterCallback<PointerUpEvent>(OnPointerUp);
    }
    protected override void UnregisterCallbacksFromTarget()
    {
        target.UnregisterCallback<PointerDownEvent>(OnPointerDown, TrickleDown.TrickleDown);
        target.UnregisterCallback<PointerUpEvent>(OnPointerUp);
    }
    void OnPointerDown(PointerDownEvent evt) => target.CapturePointer(evt.pointerId);
    void OnPointerUp(PointerUpEvent evt) => target.ReleasePointer(evt.pointerId);
}

// usage: myElement.AddManipulator(new DragHandle(myElement));

UQuery, Custom Controls, and Data Access

Manual/UIE-UQuery.html documents the LINQ-like query API (.Q<Button>("start-btn"), .Query<Label>(className: "menu-title").ToList()) used to find descendants of the visual tree by name, type, or USS class — the UI Toolkit equivalent of GameObject.Find/GetComponentInChildren. For a reusable widget, Manual/UIE-custom-controls.html covers subclassing VisualElement and registering a UxmlFactory/UxmlTraits (or the newer [UxmlElement]/[UxmlAttribute] source-generator attributes) so the control can be dropped into UXML/UI Builder like any built-in element.

using UnityEngine.UIElements;

[UxmlElement]
public partial class HealthBar : VisualElement
{
    [UxmlAttribute] public float Value { get; set; } = 1f;

    public HealthBar()
    {
        style.height = 20;
        style.backgroundColor = new StyleColor(Color.gray);
    }
}

Common Mistakes

Quick Reference

Advanced Notes

Editor-only vs runtime UI Toolkit. UI Toolkit is one API used in two very different contexts, and code/USS that works in one doesn't automatically work in the other. Editor UI (custom EditorWindows, Inspectors) uses the Editor's own implicit panel and default Editor theme, and can freely use Editor-only APIs (ObjectField, PropertyField, IMGUIContainer interop per Manual/UIE-IMGUI-migration.html). Runtime UI requires an explicit UIDocument + PanelSettings pair (Manual/UIE-Runtime-Panel-Settings.html, Manual/UIE-create-panel.html), must reference a themeStyleSheet for built-in controls to render with any chrome at all (there is no implicit Editor theme at runtime), and is subject to the runtime performance guidance in Manual/UIE-performance-consideration-runtime.html that doesn't apply to Editor tooling. Always verify a runtime panel in Play Mode/a build — the UI Builder's canvas preview approximates but does not guarantee runtime appearance, especially for theme-dependent default control styling.

Nine-slicing. Both systems support nine-slice scaling (stretching a bordered image without distorting its corners), but through different mechanisms: uGUI configures border pixels on the Sprite asset itself (Sprite Editor border handles), consumed automatically by Image when its Image Type is set to Sliced; UI Toolkit instead sets the -unity-slice-left/right/top/bottom USS properties (Manual/UIE-USS-SupportedProperties.html#unity-slice) directly on the element consuming the background-image, independent of any metadata baked into the source texture. Mismatched slice values (USS or Sprite Editor) relative to the image's actual border pixels is the most common cause of blurry or stretched-looking button/panel corners in both systems.

World-space UI differs structurally between systems. uGUI's World Space Canvas is just a Canvas whose RectTransform is treated as an ordinary 3D object sized in world units — no extra render target is involved. UI Toolkit has no native "3D transform" for a panel; instead a runtime panel is rendered into a RenderTexture (via PanelSettings.targetTexture) which is then displayed on a MeshRenderer/quad in the scene, per Manual/ui-systems/world-space-ui.html and the worked math in Manual/ui-systems/world-space-ui-size-and-position-examples.html. This means UI Toolkit world-space UI incurs an extra render-texture pass uGUI's approach does not.

Migrating from uGUI to UI Toolkit. Manual/UIE-Transitioning-From-UGUI.html is a direct concept-to-concept map (Canvas → Panel/UIDocument, RectTransform anchors → USS flexbox/positioning, Image/Text Components → VisualElement/Label with USS, prefab variants → UXML templates) and is the fastest way to translate an existing uGUI screen rather than redesigning it from scratch in UI Toolkit idioms.