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

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:

1. Trickle-down -- from root to target element
2. 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

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

Key API Quick Reference

UI Toolkit

uGUI

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