> For the complete documentation index, see [llms.txt](https://postica.gitbook.io/binding-system-3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://postica.gitbook.io/binding-system-3/overview/ui-toolkit.md). # UI Toolkit and UXML Bind UXML element properties from UI Builder, with the same pipeline. New in 3.0. A property of any `VisualElement` in a UXML document can be driven by a binding: same source modes, same paths, same converters and modifiers, same Live Debug. It works the other way round too: a [UI Document can be the source](#a-ui-document-as-a-source) of any binding, down to one element's style or USS class. {% hint style="success" %} **Learn by doing:** [A HUD in UI Toolkit](/binding-system-3/tutorials/uitoolkit-hud.md) builds a bound HUD from UI Builder and puts the two storage modes side by side. {% endhint %}

## Adding a binding 1. Open the UXML in **UI Builder**. 2. Select an element. 3. **Right click the property field** in UI Builder's Inspector, for example `text` on a `Label`. 4. Choose **Add BS3 Binding**. The bind popup opens already filled in: element, property, and the value type are all read from where you clicked. All that is left is to pick a source and a path, exactly as on any other bind field.

Right clicking a property that already has a binding offers **Edit BS3 Binding** and **Remove BS3 Binding** instead, so there is no way to end up with an accidental duplicate. Removal is offered even for a half-finished binding, which makes cleaning up a mistake one right click. ## Where the binding goes This is decided for you, by what is in the scene, in this order:

Situation	Where the binding is stored
Exactly one scene `UIDocument` uses this UXML	The binding is stored on that GameObject, in a `UIDocumentBindings` component created on demand. One click, nothing to choose.
Several `UIDocument`s use it	The menu lists them and you pick the destination once.
No scene document uses it	The binding is written into the UXML asset itself.

The scene is preferred because it can do more.

	Scene-stored	Asset-stored
Can reference scene objects	Yes	No
Travels with the UXML	No	Yes
Element identified by	Name and hierarchy path	Its place in the document, or its name when it has one. No name is needed.
Shared between users of the asset	No, per instance	Yes
Stored as	Serialized data on the component	A `bind-data` attribute on a `BS3DataBinding` tag in the file

An asset binding belongs to the element whose `Bindings` block holds it, so at runtime it needs nothing to find its element. In the editor an unnamed element is found by its place: its type and its position among siblings of that type, level by level. When an element has a name, the name is what counts, since it survives the element being moved. {% hint style="info" %} An asset binding can still reach plenty: [bind variables](/binding-system-3/overview/bind-variables.md), [static members](/binding-system-3/overview/sources.md#static), project assets. What it cannot do is name an object that only exists in one scene. {% endhint %} ## While you are in UI Builder Bound rows show the Binding System hexagon in UI Builder's Inspector, so you can see at a glance which properties are driven. When the open UXML is rendered by a `UIDocument` in a loaded scene, a pill appears in the viewport reading *Currently binding for \*, or naming the count when several documents use it. That tells you where the next **Add BS3 Binding** will land before you click it.

The scene-link pill and the bound-row hexagons

### Unsaved changes An asset binding is written into the `.uxml` file, and UI Builder keeps its own edits in memory until you save. Writing the file underneath those edits would make UI Builder ask which version to keep, and either answer loses something. So nothing is written while the document has unsaved changes:

Where	What you see
The bind popup	The Apply button reads Save and Apply, and a note above it says why. Pressing it saves the document in UI Builder first, then writes the binding.
Removing a binding	A notice in place, with a Save and Remove button.
Edit in UI Builder on the component	A notice with Save and Edit.

The save is UI Builder's own. If it is cancelled, for example on the first save of a new document, nothing is written. The same save is what makes an element you have just created bindable, since until then it is not in the file. Messages from the integration appear as short notices beside what you clicked, never as modal dialogs. Bindings are deliberately **inert inside the UI Builder canvas**. Their sources cannot resolve in an authoring context, and a failing update would show as an unresolved binding on the field, so they simply do not run there. ## The UIDocumentBindings component Sits beside the `UIDocument`, added automatically when needed. Its Inspector is where you review, validate and manage scene bindings.

Part	What it shows
Scene Bindings	The entries stored here. Each one has an element picker, a property picker and a full bind row.
UXML Asset Bindings	A foldout listing the bindings embedded in the UXML, read-only, with a Remove button. So you can see both kinds in one place.
Edit in UI Builder	Starts a round-trip session, below.
Finish Editing	Ends that session.
Validation	Reports concrete problems: no Source Asset on the document, an element that cannot be found, a property that does not exist on the element type, a bind type that does not match the property type.

Bindings are applied when the component is enabled, and re-applied automatically whenever the document rebuilds its visual tree, for example when its `visualTreeAsset` is swapped at runtime. If you mutate the tree yourself, call `Reapply()`. ```csharp var bindings = GetComponent(); bindings.Reapply(); ``` ## The round-trip session Scene bindings live on a component, but UI Builder only knows about the file. **Edit in UI Builder** bridges that: the component's entries are injected into the real `.uxml` as temporary tags, you edit them in UI Builder like any other binding, and the component is reconciled from the file on every save. **Finish Editing** strips the temporary tags. The design is crash safe by construction. The component's list is never cleared during a session, and reconciliation only ever updates entries, never deletes them. At every instant either the component alone, or the component plus the tags, holds the data. {% hint style="warning" %} Two things end a session: entering play mode, and closing the scene that owns the component. Serialized object references travel through the temporary tags as instance ids, which are only valid within one editor run. {% endhint %} If a session leaves temporary tags behind, for example after a crash, opening the component again detects them and offers to adopt or discard. ## Read and write A read pushes source values into the element. A write pushes element changes back to the source, through change events when the property is the element's `value` slot, and by polling otherwise. So a bound `Slider.value` in `ReadWrite` mode is a two-way control with no code. ## A UI Document as a source Everything above binds **into** an element. The reverse also works: give any binding a `UIDocument` as its source, and the bind path menu shows its visual tree under **UI Elements**. The element's own members, its inline style and its USS classes are all bindable, from any bind field, proxy binding or modifier operand. An element can be pointed at in three ways, each a branch of its own:

Branch	Finds the element by	Good for
Hierarchy	Its position in the tree.	The most precise. Breaks if the element moves.
By Name	Its UXML name.	Survives moving the element anywhere in the document.
By Class	A USS class.	One binding for a whole set of elements. Reads use the first match; style and class writes reach every element with the class.

Under each element:

Group	What it binds
Its members	Whatever its type exposes: `text` on a `Label`, `value` on a `Slider`, `tooltip`, and the rest.
Inline Style	The style properties worth animating, grouped as Appearance, Layout, Spacing, Border and Text. Colours bind as `Color`, lengths as a `float` in pixels.
USS Classes	Each class the element carries, as a `bool`: true adds the class, false removes it.

**By Class** also leads with **Element with classes**, which does not name a class from the document at all. It asks for the class names as [parameters](/binding-system-3/overview/paths.md#parameters), one field to start with, and the **+** and **−** buttons on the parameter group add or remove fields, up to six. It finds the first element carrying all of them, so it keeps working for elements built after the menu was opened. The internal parts of Unity's composite controls, whose names start with `unity-`, are walked through so that anything authored inside them stays reachable, but are not offered themselves. To keep the menu quick, at most 200 elements are listed. The menu is built from the document's live visual tree, or from its Source Asset when the tree has not been built yet, so a document needs a Source Asset before there is anything to list. ## From code `BS3DataBinding` is a `CustomBinding`, so it can be created and registered by hand: ```csharp using Postica.BindingSystem; using Postica.BindingSystem.UIToolkit; var binding = new BS3DataBinding(); binding.BindDataJson = serializedBindData; // what UI Builder writes into the UXML element.SetBinding("text", binding); ``` One `BS3DataBinding` instance drives one element. Registering the same instance on several elements is not supported. In UXML, the same thing looks like this. You will not normally write it by hand, but this is what ends up in the file: ```xml ``` ## Troubleshooting

Message	What it means
Select the element to bind in UI Builder first	The menu needs an element selection to know what to bind.
Right click the property to bind in the UI Builder inspector	The menu was opened somewhere other than a property field in UI Builder's Inspector.
Save this document in UI Builder first	The document has never been saved, so it has no file for an asset binding to be written into. Save it once.
… has unsaved changes in UI Builder	See Unsaved changes. Use the Save and … button beside the message.
The UI Document has no Source Asset	Assign the UXML to the `UIDocument` first. Without it no binding can resolve its element.