You can customize a UXML tag name, create custom attributes for a custom control, and add attribute decorators in UI Builder.
By default, the tag name in UXML for your custom control is the C# class name. It’s not recommended that a tag has a different name than the C# class. However, you have the option to customize the tag name.
To customize a UXML tag name, add a name
argument to the UxmlElement
attribute.
Note: The tag name must be unique and you must reference the classes’ namespace in UXML.
For example, if you create the following custom button:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlElement_CustomButtonElement.cs)]
You can then reference the custom button in UXML with the custom name or its type:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlElement_CustomButtonElement.uxml)]
To create new attributes for a custom control, add the UxmlAttribute
attribute to the custom attribute definition. By default, UI Toolkit resolves the C# Camel case or Pascal case attribute names into lowercase words connected by hyphens. For example, a property named MyFloat
or myFloat
in C# becomes my-float
in UXML and UI Builder.
The following example creates a custom control with multiple custom attributes:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlElement_ExampleElement.cs)]
The following example UXML document uses the custom control:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlElement_ExampleElement.uxml)]
You can use struct or class instances as attributes, and lists of struct or class instances as attributes. To do so, you must convert them to and from a string and declare a UxmlAttributeConverter
to support this conversion.
Note: When you use a class in a list, ensure that its string representation doesn’t contain any commas (,
) because commas are used to separate the items.
The following example creates a custom control with custom list attributes:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlAttribute_MyClassWithData.cs)]
The following example converts the custom property and declares a UxmlAttributeConverter
to support the conversion:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlAttribute_MyClassWithDataConverter.cs)]
The following example UXML document uses the custom control:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlAttribute_MyClassWithDataConverter.uxml)]
You can customize the attribute name through the name
argument of the UxmlAttribute
attribute.
The following example creates a custom control with customized attribute names:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlAttribute_CustomAttributeNameExample.cs)]
The following example UXML document uses the custom attribute names:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlAttribute_CustomAttributeNameExample.uxml)]
If you’ve changed the name of an attribute, to ensure that the UXML files with the previous attribute name can still be used, add the obsoleteNames
argument to the UxmlAttribute
attribute.
The following example creates a custom control with customized and obsolete attributes names:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlAttribute_CharacterDetails.cs)]
The following example UXML document uses obsolete names:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlAttribute_CharacterDetails.uxml)]
You can add the following decorator attributes on custom attribute fields. When you add a decorator attribute, the corresponding UI controls, such as a slider for Range
, are displayed in the UI Builder’s Inspector tab:
The following example creates a custom control with decorators on its attribute fields:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlAttribute_ExampleText.cs)]
The UI Builder displays the attributes with the decorators:
You can add custom property drawers on fields in the UI Builder.
The following example creates a custom control with a custom property drawer:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlAttribute_MyDrawerExample.cs)]
To access other serialized properties, prepend the name with serializedData
. The following code example uses serializedData.myColor
to find the myColor
attribute:
[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/Examples/UxmlAttribute_MyDrawerAttributePropertyDrawer.cs)]
The custom property drawer looks like the following:
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.