Unity UI Systems

Unity provides three UI frameworks. UI Toolkit is the recommended system for new projects. uGUI remains supported for legacy and certain runtime use cases. IMGUI is strictly for Editor tooling and debugging.

UI System Comparison

Feature	UI Toolkit	uGUI (Canvas)	IMGUI
Recommended for new projects	Yes	No (legacy)	No
Runtime game UI	Yes	Yes	Not recommended
Editor extensions	Yes	No	Yes
Approach	Web-inspired (UXML + USS + C#)	GameObject + Component	Code-only (OnGUI)
Layout system	Flexbox (Yoga)	RectTransform + Anchors	Immediate mode
Styling	USS stylesheets	Per-component properties	GUIStyle / GUISkin
Visual authoring	UI Builder	Scene View	None
Performance	Optimized retained mode	Canvas batching	Redraws every frame
Data binding	SerializedObject + Runtime binding	Manual via code	Manual via code
World-space UI	Supported	Canvas World Space mode	Not supported
Input integration	Pointer/Keyboard events	EventSystem + Raycasters	Event.current

Decision guide:

New runtime UI (menus, HUD, inventory) --> UI Toolkit
New Editor windows / inspectors --> UI Toolkit
Existing project with uGUI --> Continue with uGUI, migrate incrementally
Quick debug overlays in Editor --> IMGUI
World-space UI on 3D objects --> Either UI Toolkit or uGUI World Space Canvas

UI Toolkit

UI Toolkit is Unity's modern UI framework inspired by web technologies. It uses UXML for structure, USS for styling, and C# for logic.

Core Architecture

UIDocument (MonoBehaviour on GameObject)
  --> VisualTreeAsset (.uxml)  -- defines structure
  --> StyleSheet (.uss)         -- defines appearance
  --> C# script                 -- defines behavior

All UI elements inherit from VisualElement. The root is accessed via rootVisualElement.

UXML Structure

UXML defines the UI hierarchy declaratively:

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements">
    <ui:Style src="MainMenu.uss" />
    <ui:VisualElement name="root-container" class="container">
        <ui:Label text="Game Menu" class="title" />
        <ui:Button text="Play" name="play-button" class="menu-btn" />
        <ui:Button text="Settings" name="settings-button" class="menu-btn" />
        <ui:Toggle label="Fullscreen" name="fullscreen-toggle" />
        <ui:Slider label="Volume" low-value="0" high-value="100" name="volume-slider" />
        <ui:TextField label="Player Name" name="player-name" />
    </ui:VisualElement>
</ui:UXML>

Key points:

xmlns:ui="UnityEngine.UIElements" is the standard namespace
Reference USS files with <ui:Style src="..." />
Use name attribute for C# queries, class for USS styling
Templates can be imported: <ui:Template src="other.uxml" name="other" />

USS Styling

USS uses CSS-like syntax with Unity-specific extensions. All USS properties use the prefix -unity- for Unity-specific features.

/* Type selector */
Button {
    background-color: #2D2D2D;
    border-radius: 4px;
    padding: 8px 16px;
    -unity-font-style: bold;
}

/* Class selector */
.menu-btn {
    width: 200px;
    height: 40px;
    margin: 4px 0;
    font-size: 16px;
    color: #FFFFFF;
}

/* Name selector */
#play-button {
    background-color: #4CAF50;
}

/* Pseudo-class */
.menu-btn:hover {
    background-color: #555555;
    scale: 1.05 1.05;
}

.menu-btn:active {
    background-color: #333333;
}

.menu-btn:disabled {
    opacity: 0.5;
}

/* Descendant selector */
.container > Label {
    -unity-text-align: middle-center;
}

/* USS variables */
:root {
    --primary-color: #4CAF50;
    --font-large: 24px;
}

.title {
    color: var(--primary-color);
    font-size: var(--font-large);
}

Selector types: Type (Button), Name (#name), Class (.class), Universal (*), Descendant (A B), Child (A > B), Multiple (A.class), Pseudo-classes (:hover, :active, :focus, :disabled, :checked).

Layout is Flexbox-based: Use flex-direction, flex-grow, flex-shrink, justify-content, align-items, align-self, flex-wrap. Default direction is column.

C# Setup and Interaction

using UnityEngine;
using UnityEngine.UIElements;

public class MainMenuController : MonoBehaviour
{
    [SerializeField] private UIDocument uiDocument;

    private Button playButton;
    private Button settingsButton;
    private Toggle fullscreenToggle;
    private Slider volumeSlider;
    private TextField playerNameField;

    private void OnEnable()
    {
        var root = uiDocument.rootVisualElement;

        // Query single elements by name
        playButton = root.Q<Button>("play-button");
        settingsButton = root.Q<Button>("settings-button");
        fullscreenToggle = root.Q<Toggle>("fullscreen-toggle");
        volumeSlider = root.Q<Slider>("volume-slider");
        playerNameField = root.Q<TextField>("player-name");

        // Register click callbacks
        playButton.RegisterCallback<ClickEvent>(OnPlayClicked);
        settingsButton.RegisterCallback<ClickEvent>(OnSettingsClicked);

        // Register value change callbacks
        fullscreenToggle.RegisterValueChangedCallback(OnFullscreenChanged);
        volumeSlider.RegisterValueChangedCallback(OnVolumeChanged);

        // Query multiple elements by class
        var allButtons = root.Query<Button>(className: "menu-btn").ToList();
    }

    private void OnDisable()
    {
        playButton.UnregisterCallback<ClickEvent>(OnPlayClicked);
        settingsButton.UnregisterCallback<ClickEvent>(OnSettingsClicked);
        fullscreenToggle.UnregisterValueChangedCallback(OnFullscreenChanged);
        volumeSlider.UnregisterValueChangedCallback(OnVolumeChanged);
    }

    private void OnPlayClicked(ClickEvent evt) => Debug.Log("Play clicked");
    private void OnSettingsClicked(ClickEvent evt) => Debug.Log("Settings clicked");

    private void OnFullscreenChanged(ChangeEvent<bool> evt)
    {
        Screen.fullScreen = evt.newValue;
    }

    private void OnVolumeChanged(ChangeEvent<float> evt)
    {
        AudioListener.volume = evt.newValue / 100f;
    }
}

Programmatic UI creation (no UXML):

private void CreateUIFromCode()
{
    var root = uiDocument.rootVisualElement;

    var container = new VisualElement();
    container.AddToClassList("container");
    root.Add(container);

    var label = new Label("Created from C#");
    container.Add(label);

    var button = new Button(() => Debug.Log("Clicked")) { text = "Click Me" };
    button.name = "dynamic-button";
    container.Add(button);
}

Event System

UI Toolkit events propagate in two phases:

Trickle-down -- from root to target element
Bubble-up -- from target back to root

// Default: bubble-up phase
element.RegisterCallback<PointerDownEvent>(OnPointerDown);

// Trickle-down phase (parent reacts before children)
element.RegisterCallback<PointerDownEvent>(OnPointerDown, TrickleDown.TrickleDown);

// Pass custom data to callbacks
element.RegisterCallback<ClickEvent, string>(OnClickWithData, "my-data");

// Set value without triggering ChangeEvent
myControl.SetValueWithoutNotify(newValue);

Data Binding

SerializedObject binding (Editor / Inspector UI):

// In UXML: <ui:IntegerField binding-path="m_Health" label="Health" />
// In C#:
var healthField = new IntegerField("Health") { bindingPath = "m_Health" };
root.Add(healthField);
root.Bind(new SerializedObject(targetComponent));

Bindable objects: MonoBehaviour, ScriptableObject, native Unity types, primitives. Only the value property of INotifyValueChanged elements can be bound.

Runtime binding connects plain C# objects to UI controls, works in both Editor and runtime contexts. Set data sources on elements and define binding modes for synchronization direction.

See: references/ui-data-binding.md

Manipulators

Manipulators encapsulate event-handling logic, separating interaction from UI code:

public class DragManipulator : PointerManipulator
{
    private Vector3 startPosition;
    private bool isDragging;

    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);
    }

    private void OnPointerDown(PointerDownEvent evt)
    {
        startPosition = evt.position;
        isDragging = true;
        target.CapturePointer(evt.pointerId);
        evt.StopPropagation();
    }

    private void OnPointerMove(PointerMoveEvent evt)
    {
        if (!isDragging) return;
        var delta = evt.position - startPosition;
        target.transform.position += (Vector3)delta;
        startPosition = evt.position;
    }

    private void OnPointerUp(PointerUpEvent evt)
    {
        isDragging = false;
        target.ReleasePointer(evt.pointerId);
        evt.StopPropagation();
    }
}

// Usage:
myElement.AddManipulator(new DragManipulator(myElement));

Built-in manipulator classes: Manipulator (base), PointerManipulator, MouseManipulator, Clickable, ContextualMenuManipulator, KeyboardNavigationManipulator.

Custom Controls

// Unity 6+ recommended pattern: [UxmlElement] attribute (replaces deprecated UxmlFactory/UxmlTraits)
[UxmlElement]
public partial class HealthBar : VisualElement
{
    [UxmlAttribute]
    public float MaxHealth { get; set; } = 100f;

    private VisualElement fillBar;
    private float currentHealth;

    public float CurrentHealth
    {
        get => currentHealth;
        set
        {
            currentHealth = Mathf.Clamp(value, 0, MaxHealth);
            fillBar.style.width = Length.Percent(currentHealth / MaxHealth * 100f);
        }
    }

    public HealthBar()
    {
        AddToClassList("health-bar");
        fillBar = new VisualElement();
        fillBar.AddToClassList("health-bar__fill");
        Add(fillBar);
    }
}

uGUI / Canvas System (Legacy)

uGUI is Unity's older GameObject-based UI system. It uses Canvas, RectTransform, and the EventSystem.

Canvas Render Modes

Mode	Description	Use Case
Screen Space - Overlay	Renders on top of everything, scales with screen	Standard HUD, menus
Screen Space - Camera	Rendered by a specific camera, affected by perspective	UI with depth effects
World Space	Canvas as a 3D object in the scene	In-world displays, VR UI

Core Components

Visual: Text, Image, RawImage Interaction: Button, Toggle, ToggleGroup, Slider, Scrollbar, Dropdown, InputField, ScrollRect Layout: HorizontalLayoutGroup, VerticalLayoutGroup, GridLayoutGroup, ContentSizeFitter, AspectRatioFitter, LayoutElement

RectTransform and Anchoring

All uGUI elements use RectTransform instead of Transform. Anchors define how an element positions relative to its parent:

Anchor Min/Max as fractions (0.0 = left/bottom, 1.0 = right/top)
Together anchors: fixed position (Pos X, Pos Y, Width, Height)
Separated anchors: stretching (Left, Right, Top, Bottom padding)
Pivot: center point for rotation and scaling

uGUI Example

using UnityEngine;
using UnityEngine.UI;

public class MenuManager : MonoBehaviour
{
    [SerializeField] private Button playButton;
    [SerializeField] private Slider volumeSlider;
    [SerializeField] private Toggle muteToggle;

    private void OnEnable()
    {
        playButton.onClick.AddListener(OnPlayClicked);
        volumeSlider.onValueChanged.AddListener(OnVolumeChanged);
        muteToggle.onValueChanged.AddListener(OnMuteToggled);
    }

    private void OnDisable()
    {
        playButton.onClick.RemoveListener(OnPlayClicked);
        volumeSlider.onValueChanged.RemoveListener(OnVolumeChanged);
        muteToggle.onValueChanged.RemoveListener(OnMuteToggled);
    }

    private void OnPlayClicked() => Debug.Log("Play");
    private void OnVolumeChanged(float value) => AudioListener.volume = value;
    private void OnMuteToggled(bool muted) => AudioListener.pause = muted;
}

Draw Order

Elements render in Hierarchy order: first child drawn first, last child drawn on top. Reorder with Transform.SetAsFirstSibling(), SetAsLastSibling(), SetSiblingIndex().

See: references/ugui-legacy.md

Anti-Patterns

Anti-Pattern	Problem	Correct Approach
Using inline styles everywhere	Per-element memory overhead	Use USS files for shared styles
Universal selectors in complex USS (`A * B`)	Poor selector performance at scale	Use BEM class naming, child selectors
Heavy `:hover` on elements with many descendants	Mouse movement invalidates entire hierarchies	Limit `:hover` to leaf elements
Calling `Bind()` inside `CreateInspectorGUI()`	Double-binding, automatic binding occurs after return	Let auto-binding handle it, or call Bind only on manually created UI
Rebuilding entire UI every frame	Defeats retained-mode benefits	Update only changed elements
Multiple Canvases with dynamic content (uGUI)	Canvas rebuild batches on any child change	Split static and dynamic UI into separate Canvases
Not unregistering callbacks	Memory leaks, stale references	Always unregister in `OnDisable` or `OnDestroy`
Using IMGUI for runtime game UI	Redraws every frame, poor performance	Use UI Toolkit or uGUI
Forgetting EventSystem in scene (uGUI)	No input events processed	Ensure one EventSystem exists in scene

Key API Quick Reference

UI Toolkit

API	Purpose
`UIDocument`	MonoBehaviour that hosts a VisualTreeAsset
`rootVisualElement`	Root of the visual tree
`Q<T>("name")`	Query single element by name
`Q<T>(className: "cls")`	Query single element by class
`Query<T>().ToList()`	Query multiple elements
`RegisterCallback<TEvent>(callback)`	Register event handler
`UnregisterCallback<TEvent>(callback)`	Remove event handler
`RegisterValueChangedCallback(callback)`	Listen for value changes
`SetValueWithoutNotify(value)`	Set value silently
`AddToClassList("class")`	Add USS class
`RemoveFromClassList("class")`	Remove USS class
`AddManipulator(manipulator)`	Attach event manipulator
`style.display = DisplayStyle.None`	Hide element
`style.display = DisplayStyle.Flex`	Show element
`VisualTreeAsset.Instantiate()`	Create instance from UXML
`element.Bind(serializedObject)`	Bind to SerializedObject

uGUI

API	Purpose
`Canvas`	Root container for all uGUI elements
`CanvasScaler`	Controls UI scaling across resolutions
`GraphicRaycaster`	Enables input detection on Canvas
`EventSystem`	Central input event dispatcher
`RectTransform`	Transform with anchoring and sizing
`Button.onClick`	UnityEvent for click
`Toggle.onValueChanged`	UnityEvent for toggle change
`Slider.onValueChanged`	UnityEvent for slider change
`LayoutGroup`	Auto-layout for children

Related Skills

unity-foundations -- GameObject, Component, MonoBehaviour lifecycle
unity-scripting -- C# patterns, SerializeField, events
unity-input -- Input System integration with UI

TextMeshPro

For all text rendering, use TextMeshPro (TMP) — not legacy UI.Text. TMP uses SDF rendering for crisp text at any scale. Use TextMeshProUGUI for Canvas UI, TextMeshPro for 3D world text. Use SetText("Score: {0}", value) for zero-allocation updates. See references/textmeshpro.md for full API, rich text tags, font assets, and patterns.

Additional Resources

UI Toolkit | USS | UXML | Data Binding | Manipulators
uGUI Canvas | uGUI Layout

unity-ui

Unity UI Systems

UI System Comparison

UI Toolkit

Core Architecture

UXML Structure

USS Styling

C# Setup and Interaction

Event System

Data Binding

Manipulators

Custom Controls

uGUI / Canvas System (Legacy)

Canvas Render Modes

Core Components

RectTransform and Anchoring

uGUI Example

Draw Order

Anti-Patterns

Key API Quick Reference

UI Toolkit

uGUI

Related Skills

TextMeshPro

Additional Resources