TemplateContainer breaking Layouts

Hi, I’m just getting started with UI Toolkit and I found one of the first major annoyances you stumble across are TemplateContainers that are getting instantiated as parents against my will and breaking my layouts.

I’ve seen people complaining about this a lot and using workarounds by loading the first child instead. But having to workaround every time I need to do some basic instantiation, points to an architectural issue. I don’t see any situation where this would be a behavior that makes sense.

If I’m designing my dynamic UI elements to behave a certain way, I don’t want to repair the instance again after using VisualTreeAsset.Instantiate() because Unity thinks it has to patronize me.
This not only makes starting to work with UI Toolkit a pain, when getting unexpected behavior while trying to learn the underlying concepts but also introduces workarounds for every dynamic UI, which is basically most of the UI you write.

Is there any plan to change this, or an official way to keep your layouts intact like VisualTreeAsset.Instantiate(actualTemplate: true)?

I think this is a major flaw and makes working with dynamic UI feel a lot less production ready than it should be. Seeing these types of workarounds for basic problems makes me not consider UI Toolkit to be used in production.

Yeah I would honestly like TemplateContainers to be scrapped. I don’t really understand what use they provide, and perhaps a Unity UI Toolkit dev could elucidate me on the matter, but I see only complaints about them.

To that end I just don’t use them whatsoever. I’ll just instantiate custom controls via code, and use style sheets on the relevant UI Documents to style them.

I believe if you call CloneTree (instead of Instantiate) and pass it the item you’d like to be the root of the visual element it will bypass creating the TemplateContainer.

Wholeheartedly agree with you, would be great to get an official Unity opinion on this as they’ve ghosted these types of threads for over a year now.

As @rocknrye mentioned, there is an overload method CloneTree(VisualElement root) available to instantiate UXML without a TemplateContainer, as long as you manually pass in the root. This is great, however, it breaks the workflow available to us in UIBuilder. Why force us to use TemplateContainers in UIBuilder? It’s such a pain for a number of reasons

  • No easy way to customize the style of the TemplateContainer
  • Makes inheritance clunky and difficult when using UXML
  • Inherently surprising and unpredictable from a user standpoint. The fact that certain style values are baked in, like grow=0 completely breaks layouts very often.

Most recently I got frustrated because I had a UIDocument I wanted to toggle on and off. The UIDocument gets instantiated with a TemplateContainer by default. When I get the root of the UIDocument and set its style property display=Display.None, it is setting the TemplateContainer’s display property. However, when I open up the UXML in UIBuilder to turn it off manually, I don’t have access to the TemplateContainer’s style property - thus breaking my Unity workflow in the Editor.

I could get the first child of the TemplateContainer and set that to hide, but then the TemplateContainer is still just sitting there and could mess with other layouts. It seems I’m forced out of using UIBuilder and have to control everything via C# in this case…super annoying.

What’s even worse is if you disable the GameObject or the UIDocument component itself, UIToolkit automatically deletes child elements, which has been discussed elsewhere. An editor workflow is actively being discouraged. Ok I get it - you want us to use UIBuilder. Then give us some TemplateContainer tools.

You can try and protect yourself from some of the poor choices Unity make by creating and ExtentionFunction library that reminds yourself and gives yourself tools.

For instance I have these two extension methods:

         // When you .Instantiate() from a VisualAssetTree you get a TemplateContainer containing your VisualElement.
        // This is a type of VisualElement so it's easy to add it as a child to other VisualElements, but if you do
        // you'll get strange layout behaviour. Instead get a VisualElement.
        public static void Add(this VisualElement element, TemplateContainer templateContainer)
        {
            VisualElement visualElement = templateContainer.ElementAt(0);
            element.Add(visualElement);
        }
        
        public static VisualElement InstantiateProperly(this VisualTreeAsset visualTreeAsset)
        {
            return visualTreeAsset.Instantiate().ElementAt(0);
        }