A good custom control is abstract, self-contained, and recurring.
A Slide Toggle is a good example of a custom control:
The menu bar of your application isn’t a good example of a custom control:
After you have created a custom control, you can style it with USS and add logic to handle events in C#.
To create a custom control, do the following:
UxmlElement attribute to the custom control class definition.VisualElement or one of its derived classes.For example:
using UnityEngine;
using UnityEngine.UIElements;
[UxmlElement]
public partial class ExampleElement : VisualElement {}
You can use your custom controls in UXML and UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary Builder after you create them.
The following example UXML document uses the custom control:
<ui:UXML xmlns:ui="UnityEngine.UIElements">
<ExampleElement />
</ui:UXML>
By default, the custom control appears in the Library tab in UI Builder. If you want to hide it from the Library tab, add the HideInInspector attribute.
Custom controls inherit from VisualElement. A VisualElement isn’t bound to the lifetime of a GameObjectThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary and doesn’t receive any of these callbacks:
Awake()OnEnable()OnDisable()OnDestroy()You can initialize a custom control in its constructor. However, if your application needs it, you can delay initialization until the custom control is added to the UI. To do this, register a callback for an AttachToPanelEvent. To detect that your custom control has been removed from the UI, use the DetachFromPanelEvent callback.
public CustomControl()
{
var myCustomElement = rootVisualElement.Q(className: "my-custom-element");
myCustomElement.RegisterCallback<AttachToPanelEvent>(e =>
{ /* do something here when element is added to UI */ });
myCustomElement.RegisterCallback<DetachFromPanelEvent>(e =>
{ /* do something here when element is removed from UI */ });
}
UI Toolkit dispatches these two events for all elements and doesn’t need a custom VisualElement subclass. For more information, refer to Panel events.
Use USS to customize the look of a custom control the same way as a built-in control. You can also create USS custom properties to style a custom control.
Note: The InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
See in Glossary window in the UI Builder doesn’t show USS custom properties. To edit USS custom properties, use a text editor to edit your USS file directly.
To interact with custom USS properties for a custom control in C#, use the CustomStyleProperty structure and the CustomStylesResolvedEvent event.
CustomStyleProperty describes the name and type of property you read from the stylesheet.
UI Toolkit dispatches CustomStylesResolvedEvent for any element that directly receives a custom USS property. It dispatches the event for any element that a selector matches, for selectors where the rule contains the value of the custom property. UI Toolkit doesn’t dispatch the event for elements that inherit the value. The event holds a reference to an ICustomStyle object. You must use its TryGetValue() method to read the effective value of a CustomStyleProperty. This method has overloads for different types of CustomStyleProperty.
For a custom style with a custom control example, refer to Create custom style for a custom control.
Note: You can’t define transitions for custom style properties.
For detailed information on how to handle events for custom controls, refer to Handle events.
Note:
focus.Expose properties that a custom control represents and other functional aspects of its behavior as UXML properties, and expose properties that affect the look of a custom control as USS properties.
Use a namespace that’s unique, short, and readable to avoid name collisionsA collision occurs when the physics engine detects that the colliders of two GameObjects make contact or overlap, when at least one has a Rigidbody component and is in motion. More info
See in Glossary with other elements.
Keep UXML attributes primitive. Data that you can specify in UXML is limited to a set of primitive data types. UXML doesn’t support complex data structures or collections. Pass complex data to your custom controls at runtime via C# scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary or data binding, not in UXML.
In C#, expose USS classes or names as constants. This allows you to locate elements by class or name using UQuery.
Adopt the BEM standard for USS classes. This allows you to address every element with a class list selector.
Use static callbacks for a lower memory footprint. When you register an instance method to be used as a callback, you might create unnecessary allocations. To avoid allocations, use anonymous static lambda functions that call into regular C# static methods. You can retrieve the context of the current element through the EventBase.currentTarget property.
Render custom geometry through the generateVisualContent callback for custom controls. For an example usage that renders a partially filled circle, refer to the RadialProgress example.
Custom controls are convenient. However, you might achieve the same outcomes with the following:
MonoBehaviours to add logic that pertains to the specific UI Document that holds your UI. (To learn how to use MonoBehaviours to control UI in a UI Document, see Create your first runtime UI.) To achieve encapsulation, create properties and methods inside your MonoBehaviour that internally fetch VisualElements with UQuery and manipulate their properties.