Get started with runtime binding

Version: 2023.2+

Want to learn how to create runtime data binding? Use this example to get started. This example creates a data source asset and uses UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary Builder to bind the data source to a UI.

Example overview

This example demonstrates the following:

• How to create a data source asset that contains the properties you want to bind to.
• How to bind the UI to the data source asset you created in UI Builder.
• The different binding modes you can use to configure how changes are replicated between the data source and the UI. For more information about binding modes, refer to Define binding modes.
• How to create a type converter to convert data types between the data source and the UI. For more information about type converters, refer to Convert data types.

You can find the completed files that this example creates in this GitHub repository.

Prerequisites

This guide is for developers familiar with the Unity Editor, UI Toolkit, and C# scripting. Before you start, get familiar with the following:

• UI Builder
• UXML

Create a data source asset

Create a data source asset that contains the properties you want to bind to. In this example, you create a ScriptableObject asset named ExampleObject that contains a string property, a Vector3 property, and a float property. The float property is a read-only property that returns the sum of the x, y, and z values of the Vector3 property. The data source asset also contains a local converter that converts a float to a Color and a string.

1. Create a project in Unity with any template.

2. In the Assets folder of your project, create a C# script named ExampleObject.cs with the following content:

   using Unity.Properties;
   using UnityEditor;
   using UnityEngine;
   using UnityEngine.UIElements;
       
   [CreateAssetMenu]
   public class ExampleObject : ScriptableObject
   {
       [InitializeOnLoadMethod]
       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("Bind to multiple properties")]
       public string vector3Label;
       public Vector3 vector3Value;
       
       [CreateProperty]
       public float sumOfVector3Properties => vector3Value.x + vector3Value.y + vector3Value.z;
       
       [Header("Binding using a converter group")]
       [Range(0, 1)] public float dangerLevel;
   }
   

3. From the menu, select Assets > Create > Example Object. This creates an asset in the Assets folder of your project.

4. Rename the asset as ExampleObject.asset.

Create the UI

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 VisualElement with a Vector3Field, a FloatField, and a Label as its child elements.

1. In the Assets folder of your project, create a UXML file named ExampleObject.uxml.
2. Double-click the ExampleObject.uxml file to open it in UI Builder.
3. In the Hierarchy panel, add a VisualElement.
4. Select the VisualElement in the Hierarchy panel.
5. Add a Vector3Field, a FloatField, and a Label as the child elements of the VisualElement.

Bind the Vector3Field to the data source

Bind the UI to the data source asset you created in the previous step. Set the data source for the root VisualElement and bind the label and value properties of the Vector3Field elements to the vector3Label and the vector3Value properties of the data source asset.

1. In the Inspector panel of the VisualElement, from the Bindings > Data Source > Asset list, select ExampleObject.
2. 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 of the Vector3Field, right-click the Label property and select Add binding.
3. In the Add Binding window, from the Data Source Path list, select vector3Label.
4. From the Binding Mode list, select To Target. This updates UI when the data source changes.
5. Select Add binding to save your changes.
6. In the Inspector panel, right-click the Value property and select Add binding.
7. In the Add Binding window, select vector3Value from the Data Source Path list.
8. From the Binding Mode list, select To Source. This updates the data source when UI changes.
9. Select Add binding to save your changes.

Bind the Float to the data source

Bind the value property of the Float to the sumOfVector3Properties property of the data source asset.

1. In the Inspector panel of the Float, right-click the Value property and select Add binding.
2. In the Add Binding window, from the Data Source Path list, select sumOfVector3Properties.
3. From the Binding Mode list, select To Target. This updates the UI when the data source changes.
4. Select Add binding to save your changes.

Bind the Label to the data source

Bind the properties of the Label to the properties of the data source asset and apply the type converter for the Label.

1. In the Hierarchy panel, select the Label.

2. In the Inspector panel, right-click the Text property and select Add binding.

3. In the Add Binding window, do the following:

   • From the Data Source Path list, select dangerLevel.
   • From the Binding Mode list, select To Target. This updates the UI when the data source changes.
   • From the Advanced Settings > Converters > To target property (UI) list, select Value To Progress. This converts a float to a string.

4. Select Add binding to save your changes.

5. In the Inspector panel, expand the Background field.

6. Right-click the Color property and select Add binding.

7. In the Add Binding window, do the following:

   • From the Data Source Path list, select dangerLevel.
   • From the Binding Mode list, select To Target. This updates the UI when the data source changes.
   • From the Advanced Settings > Converters > To target property (UI) list, select Value To Progress. This converts a float to a color.

8. Select Add binding to save your changes.

9. Save and close UI Builder. Your ExampleObject.uxml file looks like the following content:

   <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:VisualElement data-source="ExampleObject.asset" name="VisualElement" >
           <ui:Vector3Field label="Vec3 Field">
               <Bindings>
                   <ui:DataBinding property="label" data-source-path="vector3Label" binding-mode="ToSource" />
                   <ui:DataBinding property="value" data-source-path="vector3Value" />
               </Bindings>
           </ui:Vector3Field>
           <ui:FloatField label="Float Field" value="42.2">
               <Bindings>
                   <ui:DataBinding property="value" data-source-path="sumOfVector3Properties" binding-mode="ToTarget" />
               </Bindings>
           </ui:FloatField>
           <ui:Label text="Label" data-source-path="dangerLevel">
               <Bindings>
                   <ui:DataBinding property="text" binding-mode="ToTarget" source-to-ui-converters="Value To Progress" />
                   <ui:DataBinding property="style.backgroundColor" binding-mode="ToTarget" source-to-ui-converters="Value To Progress" />
               </Bindings>
       </ui:Label>
       </ui:VisualElement>
   </ui:UXML>
   

Test the binding in UI Builder preview mode

Update the label text of the Vector3Field in the data source asset to see changes replicated in the UI. Update the value of the Vector3 property in the UI to see changes replicated in the data source asset. Move the slider of the danger level in the data source to see changes replicated in the Label.

1. In the Assets folder of your project, select the ExampleObject.asset file.
2. In the Inspector window, in the Vector 3 Label field, enter a random text. The label of the Vector3Field in the UI Builder ViewportThe user’s visible area of an app on their screen.
   See in Glossary changes to the text you entered.
3. In the UI Builder Viewport, select Preview.
4. Enter random numbers in the X, Y, and Z fields of the Vector3Field. The Vector3 Value in the Inspector window of the ExampleObject.asset changes to the numbers you entered.
5. 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 Viewport change according to the value of the Danger Level.

Additional resources

• Runtime data binding
• Create runtime data binding
• Create custom binding types
• Define a data source
• Define logging levels