Version: 6000.0+
This example demonstrates how to create a type converter to convert data types between a data source and the UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary.
This example creates a Label control in UI Builder that binds to a data source asset. The data source asset contains a float property named dangerLevel
. The label displays the dangerLevel
as a string and changes its background color based on the value of the dangerLevel
.
You can find the completed files that this example creates in this GitHub repository.
This guide is for developers familiar with the Unity Editor, UI Toolkit, and C# scripting. Before you start, get familiar with the following:
Create a data source asset that contains the properties you want to bind to. In this example, you create a ScriptableObject
asset named ExampleConverterObject
that contains a local converter that converts a float
to a Color
and a string
.
Assets
folder of your project, create a C# script named ExampleConverterObject.cs
with the following content:using Unity.Properties;
using UnityEngine;
using UnityEngine.UIElements;
#if UNITY_EDITOR
using UnityEditor;
#endif
[CreateAssetMenu]
public class ExampleConverterObject : ScriptableObject
{
#if UNITY_EDITOR
[InitializeOnLoadMethod]
#else
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
#endif
public static void RegisterConverters()
{
// Create local Converters.
var group = new ConverterGroup("Value To Progress");
// Converter groups can have multiple converters. This example converts a float to both a color and a string.
group.AddConverter((ref float v) => new StyleColor(Color.Lerp(Color.red, Color.green, v)));
group.AddConverter((ref float value) =>
{
return value switch
{
>= 0 and < 1.0f/3.0f => "Danger",
>= 1.0f/3.0f and < 2.0f/3.0f => "Neutral",
_ => "Good"
};
});
// Register the converter group in InitializeOnLoadMethod to make it accessible from the UI Builder.
ConverterGroups.RegisterConverterGroup(group);
}
[Header("Binding using a converter group")]
[Range(0, 1)] public float dangerLevel;
}
Assets
folder of your project.ExampleConverterObject.asset
.Create a UI that binds to the data source asset you created in the previous step. In this example, you create a UXML file that contains a Label control.
Assets
folder of your project, create a UXML file named ExampleConverterObject.uxml
.ExampleConverterObject.uxml
file to open it in UI Builder.Bind the properties of the Label to the properties of the data source asset and apply the type converter for the Label.
In the Hierarchy panel, select the Label.
In the Inspector panel, from the Bindings > Data Source > Object list, select ExampleConverterObject.
From the Data Source Path list, select dangerLevel.
In 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 panel, right-click the Text field and select Add binding.
In the Add Binding window, do the following:
Select Add binding to apply your changes.
In the Inspector panel, expand the Background field.
Right-click the Color property and select Add binding.
In the Add Binding window, do the following:
Select Add binding to apply your changes.
Save and close UI Builder. Your ExampleConverterObject.uxml
file looks like the following:
<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" xsi="http://www.w3.org/2001/XMLSchema-instance"
engine="UnityEngine.UIElements" editor="UnityEditor.UIElements" noNamespaceSchemaLocation="../UIElementsSchema/UIElements.xsd" editor-extension-mode="False">
<ui:Label text="Label" data-source="ExampleConverterObject.asset" data-source-path="dangerLevel">
<Bindings>
<ui:DataBinding property="style.backgroundColor" binding-mode="ToTarget" source-to-ui-converters="Value To Progress" />
<ui:DataBinding property="text" binding-mode="ToTarget" source-to-ui-converters="Value To Progress" />
</Bindings>
</ui:Label>
</ui:UXML>
In the Inspector window of the ExampleObject.asset
, move the Danger Level slider. The text and the background color of the Label in the UI Builder ViewportThe user’s visible area of an app on their screen.
See in Glossary change according to the value of the Danger Level.
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.