UI Toolkit vs Canvas: Living With Two Unity UI Systems

Unity ships two runtime UI systems that solve overlapping problems, and choosing between them is usually framed as a religious war. It isn't one: after building both card-table screens and tower-defense HUDs, we've found the honest answer is per-screen, not per-project. This post lays out where each system gives less resistance, how team habit and editor tooling weigh in, and a checklist you can apply to your next screen.

What Unity itself says, and what that leaves open

Unity's own documentation recommends UI Toolkit for new UI development projects while noting that UGUI and IMGUI remain appropriate for certain use cases and for supporting older projects (UI Toolkit manual). The comparison of UI systems page is more specific: it positions UI Toolkit as an alternative to UGUI for screen-overlay UI running across a wide range of resolutions, and keeps UGUI as the recommendation when you need things UI Toolkit doesn't cover, such as custom shaders and materials on UI elements.

Two capability gaps that used to force the decision have narrowed recently. Unity 6 added a runtime data binding system for UI Toolkit, which connects visual elements to data sources through DataBinding objects instead of manual update loops (Unity manual). And world-space rendering for UI Toolkit arrived in Unity 6.2; the XR Interaction Toolkit documentation states plainly that world-space support for UI Toolkit is only available in Unity 6.2 and later (XRI 3.2 docs). If you're on an older LTS — which many mobile projects are, for good reasons — that second one still decides the matter for you.

Where UI Toolkit resists less

Editor tools. This is the least controversial case. If you're writing an EditorWindow, a custom inspector, or a data-authoring panel, UI Toolkit is the path with the fewest surprises. Layout is flexbox, styling lives in USS, and ListView gives you virtualization for free instead of you writing a scroll-recycler by hand. We leaned on this heavily while building the shared internal tooling described in Two Games, One Codebase: an editor tool that nobody ships doesn't need to look perfect, it needs to be written in an afternoon.

using System.Collections.Generic;
using System.Linq;
using UnityEditor;
using UnityEngine.UIElements;

public class CardListWindow : EditorWindow
{
    private readonly List<string> _all = new() { "ace", "joker", "knight", "page" };
    private List<string> _shown;

    [MenuItem("Tools/Card List")]
    private static void Open() => GetWindow<CardListWindow>("Card List");

    private void CreateGUI()
    {
        _shown = new List<string>(_all);

        var search = new TextField("Filter");
        var list = new ListView
        {
            itemsSource = _shown,
            fixedItemHeight = 20f,
            makeItem = () => new Label(),
            bindItem = (element, i) => ((Label)element).text = _shown[i]
        };
        list.style.flexGrow = 1f;

        search.RegisterValueChangedCallback(evt =>
        {
            _shown.Clear();
            _shown.AddRange(_all.Where(c => c.Contains(evt.newValue)));
            list.Rebuild();
        });

        rootVisualElement.Add(search);
        rootVisualElement.Add(list);
    }
}

Dense, text-heavy, list-shaped screens. Settings, leaderboards, inventories, patch notes, card collections. Anything that is fundamentally a document benefits from a document-shaped system: percentage widths, wrapping, and style classes beat nesting six Layout Groups and praying at rebuild time.

Screens that must survive many aspect ratios. Web builds and Android's device spread punish fixed layouts. USS media-style adjustments through class swapping are easier to reason about than juggling anchors and a Canvas Scaler reference resolution. We wrote about how wide that hardware spread gets in Not a Bug, the Device.

UI that changes often during production. When the layout is in UXML and the look is in USS, a restyle doesn't touch prefabs, which means it doesn't produce a merge conflict that only one person on the team can resolve.

Where UGUI/Canvas resists less

Anything that must live in the scene. Health bars over towers, damage numbers, range indicators, drag ghosts that follow a world position. On a pre-6.2 editor version this is UGUI's territory by definition, and even on 6.2+ the UGUI path is the one your existing code already knows. For a tower defense layout like Thornguard, most of the interesting UI is attached to something in the world, not floating above it.

UI that is really art. Custom shaders, masked materials, particle systems interleaved between UI layers, sprite atlases with per-element materials. The comparison page names custom shaders and materials as a UGUI strength, and that matches what we hit: the moment a card needs a shimmer material or a shader-driven reveal, the UI Toolkit path becomes a research project and the Canvas path is a component.

Animation authored by whoever isn't the programmer. Animator clips, tween libraries operating on RectTransform, and the Game view as a direct manipulation surface are all things artists and designers already use. This matters more than it looks in a small team.

Screens whose readability is tuned pixel by pixel. Card faces are the example we know best — the tradeoffs are in Card UI Readability vs Aesthetics. When you're nudging a rank glyph two pixels and comparing three variants side by side, prefab variants are a real workflow, and UI Toolkit has no equivalent to a prefab variant.

Team habit is a real cost, not an excuse

The technical differences between the two systems are smaller than the difference between a team that knows one and a team that doesn't. Someone who has spent years with anchors, pivots, and Layout Groups will produce a correct UGUI screen faster than a correct UI Toolkit screen, even if the UI Toolkit version would be shorter. That gap closes, but it closes over weeks, and it closes on your schedule.

The practical way to pay for it is to learn UI Toolkit on editor tools first. Editor tooling has no shipping risk, no device testing burden, and no artist dependency. By the time you write your first runtime UXML, the flexbox model and the query API are already familiar.

using UnityEngine;
using UnityEngine.UIElements;

[RequireComponent(typeof(UIDocument))]
public class PauseMenu : MonoBehaviour
{
    private void OnEnable()
    {
        var root = GetComponent<UIDocument>().rootVisualElement;
        root.Q<Button>("resume").clicked += () => Time.timeScale = 1f;
        root.Q<Button>("restart").clicked += () => Time.timeScale = 1f;
    }
}

The checklist we actually use

• Editor window or custom inspector? UI Toolkit. No discussion.
• Positioned in the world, and you're not on Unity 6.2+? UGUI.
• Needs a custom shader or material per element? UGUI.
• Long scrolling list with dozens or hundreds of rows? UI Toolkit, for the built-in virtualization.
• Layout must hold across a wide resolution and aspect-ratio range? UI Toolkit.
• Heavily animated, artist-authored, hand-tuned screen? UGUI.
• Deadline this week and only one person knows one system? That system. Skill availability is a legitimate technical constraint.

What living with both actually costs

Mixing them isn't free, and pretending otherwise is how you end up with a UI layer nobody wants to touch:

• Two mental models for layering. A UI Toolkit panel and a Canvas both claim to be on top. Sort order between a PanelSettings asset and a Canvas needs to be decided once, written down, and never improvised.
• Two input paths. Click-through and blocking rules differ. Any screen where both systems are visible at once needs an explicit rule for who consumes the pointer.
• Two debugging toolchains. The UI Debugger for UI Toolkit, the Scene view hierarchy for Canvas. Both add work on mobile, where UI rebuild cost is one of the usual suspects behind frame spikes — the hunt we described in Unity Profiler on Mobile.
• Two sets of shared components. A button style defined in USS doesn't help a prefab button. Duplicated design tokens drift within a month unless one of them is generated from the other.

Our rule is to draw the line at a screen boundary, never inside one. A screen is entirely UI Toolkit or entirely Canvas; overlays on top of the world use one system consistently across the whole project. That keeps the cost to "two systems in the project" instead of "two systems in every file".

There's no winner here. There's a per-screen question with a mostly obvious answer once you ask it out loud, and a team cost that you either pay deliberately on low-risk work or accidentally under deadline.