Skip to content

t1k:unity:ui:toolkit

FieldValue
Moduleui
Version3.43.4
Effortmedium
Tools—

Keywords: UI Toolkit, USS, UXML

/t1k:unity:ui:toolkit

Unity UI Toolkit — UXML, USS & Runtime UI

Section titled “Unity UI Toolkit — UXML, USS & Runtime UI”

UI Toolkit reference for Unity 6 (6000.x). Preferred over UGUI for new UI, including world-space since Unity 6 made it a first-class render mode.

UI Toolkit is a builtin editor module in Unity 6 — there is no com.unity.ui package to install.

You are doing…Read
Authoring UXML, writing USS, fixing layout / “my element is 0-sized”uxml-uss-and-patterns.md (references/uxml-uss-and-patterns.md)
Binding UI to data (dataSource, SetBinding, [CreateProperty])data-binding.md (references/data-binding.md)
Writing a custom VisualElement, or migrating off UxmlFactory/UxmlTraitscustom-controls.md (references/custom-controls.md)
UIDocument/PanelSettings, scale modes, world-space, safe area, Editor UIruntime-panels-and-worldspace.md (references/runtime-panels-and-worldspace.md)
Picking a control, event handling, ListView/virtualization, performancecontrols-events-and-performance.md (references/controls-events-and-performance.md)
FeatureUI ToolkitUGUI (Canvas)
Editor UIYesNo
Runtime menus/HUDYes (preferred)Yes
World-space UIYes — Panel Settings Render Mode = World Space (Unity 6)Yes, more battle-tested
Data bindingBuilt-in runtime binding systemManual
Per-element 3D transform / custom shadersLimitedYes
PerformanceRetained mode, batchedImmediate-mode rebuilds

Prefer UI Toolkit for new work. Reach for UGUI when you need per-element custom shaders/materials, a mature world-space stack, or an existing UGUI codebase.

  1. Create a Panel Settings asset: Assets → Create → UI Toolkit → Panel Settings
  2. Create a UI Document (UXML): Assets → Create → UI Toolkit → UI Document
  3. Add a UIDocument component to a GameObject → assign Panel Settings + the UXML source asset
  4. Query and wire elements from uiDocument.rootVisualElement in OnEnable

Unity 6 — what changed (a stale skill will get these wrong)

Section titled “Unity 6 — what changed (a stale skill will get these wrong)”
  1. Runtime data binding exists. element.dataSource + SetBinding("text", new DataBinding { … }) with [CreateProperty] on the bound property. This is separate from the old Editor-only SerializedObject binding. → references/data-binding.md
  2. Custom controls use [UxmlElement] / [UxmlAttribute]. The class must be partial. UxmlFactory/UxmlTraits are the legacy path. → references/custom-controls.md
  3. World-space UI is a Render Mode, not a workaround. Set Panel Settings Render Mode = World Space and add a Panel Input Configuration component for input. → references/runtime-panels-and-worldspace.md
  1. Q() returns null — name/type mismatch, or the UXML has not been cloned into the panel yet.
  2. Styles not applying — the USS must be linked from UXML (<Style src="…">) or added via styleSheets.Add(); also check selector specificity.
  3. Element invisible / zero-sized — almost always flexbox: no flex-grow, no explicit size, or a parent with no height. See the troubleshooting list in uxml-uss-and-patterns.md.
  4. Cached element references go stale — rootVisualElement is rebuilt when the UIDocument re-enables. Re-query in OnEnable; do not cache across disable/enable.
  5. Pooled ListView items bleed state — bindItem must fully reset every visual it touches.
  6. Invisible overlay eats taps — set pickingMode = PickingMode.Ignore on non-interactive overlays.
  7. Fonts — use -unity-font-definition for TextMeshPro font assets in USS.
  • UI is Tier-3 MonoBehaviour, never an ECS system. Menus, shops, HUD screens and settings are stateful and small-data. In a plain MonoBehaviour project, drive them directly from your own model/events. In a DOTS project (Packages/manifest.json lists com.unity.entities), drive them from a thin bridge that reads ECS singletons — see t1k-unity-dots-core-architecture. Do not introduce ECS types into a project that has none.
  • Addressables only — no Resources.Load in runtime asmdefs when loading UXML/USS assets.
  • C# style per rules/code-conventions-unity.md: private fields camelCase (no underscore prefix), this. prefix, [SerializeField] private.
  • Avoid System.Linq and per-frame string allocation in UI update paths; prefer ZString.
  • t1k:unity:ui:ugui — Canvas/UGUI, plus the DOTS→UI bridge patterns (DOTS projects only)
  • t1k:unity:ui:mobile-ui — touch ergonomics, thumb reach, portrait layout
  • t1k:unity:base:localization — localized UI strings
  • t1k:unity:base:input-system — UI navigation input
  • t1k:unity:base:addressables — loading UI assets on demand
FileContents
uxml-uss-and-patterns.md (references/uxml-uss-and-patterns.md)UXML structure + templates, USS selectors/variables/transitions/theming, flexbox layout, zero-size troubleshooting, mobile sizing
data-binding.md (references/data-binding.md)Runtime binding vs legacy SerializedObject binding, dataSource/SetBinding/PropertyPath, [CreateProperty], BindingMode, change notification, converters, diagnostics
custom-controls.md (references/custom-controls.md)[UxmlElement]/[UxmlAttribute], migration off UxmlFactory/UxmlTraits, composite controls, custom painting, styling hooks
runtime-panels-and-worldspace.md (references/runtime-panels-and-worldspace.md)UIDocument/PanelSettings, scale modes for portrait mobile, world-space render mode + Panel Input Configuration, safe area, runtime input, Editor UI
controls-events-and-performance.md (references/controls-events-and-performance.md)Control catalogue, querying, event phases + key events, ListView/MultiColumn virtualization, performance and profiling

A visible change made with this skill (UI, sprites, 3D, shaders, VFX, animation, lighting, scene layout; audio excluded) follows core rule visual-change-discord-notice:

  • Capture OLD before the first edit and NEW after the last (screen: ScreenCapture in Play mode per t1k-unity-editor-cli, windowed or Xvfb only because rendering is needed; 3D, shader, VFX: same-scene frame grab; 2D asset: the file).
  • Return the paths and a draft Discord post to the orchestrator, which posts; the PR links the post or carries visual-notice-waiver: <reason>. Logic only: “no visible change”. No capture: “screenshots pending: ”, never a fake image.