Unity 6 introduces improvements that simplify the creation of custom controls. This guide explains how to migrate custom controls from previous versions to Unity 6’s revamped workflow.
Previously, creating a custom control required using the UxmlTraits class to define attributes. The following example demonstrates this approach for a ProgressBar control.
The examples focus on attribute authoring and don’t include the behavior of the control. It creates a UxmlTraits class that defines the attributes of the ProgressBar control. For each attribute, the class specifies the following:
Then, it gets the value for each attribute and assigns it to the element. It also adds a UxmlFactory class that creates instances of the element.
using UnityEngine.UIElements;
public class ProgressBar : VisualElement
{
public new class UxmlFactory : UxmlFactory<ProgressBar, UxmlTraits> { }
public new class UxmlTraits : BindableElement.UxmlTraits
{
UxmlFloatAttributeDescription m_LowValue = new UxmlFloatAttributeDescription { name = "low-value", defaultValue = 0 };
UxmlFloatAttributeDescription m_HighValue = new UxmlFloatAttributeDescription { name = "high-value", defaultValue = 100 };
UxmlFloatAttributeDescription m_Value = new UxmlFloatAttributeDescription { name = "value", defaultValue = 0 };
UxmlStringAttributeDescription m_Title = new UxmlStringAttributeDescription() { name = "title", defaultValue = string.Empty };
public override void Init(VisualElement ve, IUxmlAttributes bag, CreationContext cc)
{
base.Init(ve, bag, cc);
var bar = ve as ProgressBar;
bar.lowValue = m_LowValue.GetValueFromBag(bag, cc);
bar.highValue = m_HighValue.GetValueFromBag(bag, cc);
bar.value = m_Value.GetValueFromBag(bag, cc);
bar.title = m_Title.GetValueFromBag(bag, cc);
}
}
public string title { get; set; }
public float lowValue { get; set; }
public float highValue { get; set; }
public float value { get; set; }
}
Unity 6 simplifies custom control creation with the UxmlElement and UxmlAttribute attributes, eliminating the need for UxmlTraits and UxmlFactory. The new system streamlines the process by automatically handling the conversion of values to and from UXML attribute strings.
The following shows the updated the ProgressBar example:
using UnityEngine.UIElements;
[UxmlElement]
public partial class ProgressBar : VisualElement
{
[UxmlAttribute]
public string title { get; set; }
[UxmlAttribute]
public float lowValue { get; set; }
[UxmlAttribute]
public float highValue { get; set; } = 100;
[UxmlAttribute]
public float value { get; set; }
}
Here’s the key changes:
UxmlElement to declare a custom control.UxmlAttribute to define attributes, removing the need for UxmlTraits.The UXML usage remains the same for both systems:
<ui:UXML xmlns:ui="UnityEngine.UIElements">
<ProgressBar title="My Progress bar" low-value="0" high-value="1" value="0.5" />
</ui:UXML>
If an element lacks the UxmlElement attribute, Unity defaults to the UxmlTraits and UxmlFactory systems for serialization. Ensure consistency by using a single serialization approach per visual elementA node of a visual tree that instantiates or derives from the C# VisualElement class. You can style the look, define the behaviour, and display it on screen as part of the UI. More info
See in Glossary. While both systems can coexist in a UXML file, don’t mix them with a single element.
After migrating to the new system, reimport UXML assets to match the updated code. While this process happens automatically, but any previously built Asset Bundles containing UXML files need to be rebuilt to function correctly.