A linker component resolves one element from a UIDocument and exposes it as its concrete UI Toolkit type.

Set up a linker

1. Create a UIDocument with a UXML asset and PanelSettings.
2. Add the ULB linker that matches the target element type, for example UitkButton for Button.
3. Assign the UIDocument field.
4. Choose a Linking Mode and fill the locator field shown for that mode.
5. Enable Debug when you need hierarchy-search diagnostics.
6. After LinkElement runs, access the result through Element or E.

Linking modes

Name

Name calls Query on the UIDocument root with the configured Name. Use it when the element name is unique and hierarchy changes should not matter.

IndexNames

IndexNames follows the configured Names array one hierarchy segment at a time. A segment with Index = -1 matches its Name. Any other Index selects that child position and does not validate the segment Name. This is the default mode.

Guid

Guid recursively scans descendants for one ULB element whose IHaveGuid.guid value matches the configured Guid. It tolerates parent hierarchy changes but can scan a large part of the tree.

Guids

Guids follows an exact branch of GUID values. Every matched segment must implement IHaveGuid. It searches less of the tree, but the saved path must be updated when a parent in that branch changes.

Copy a hierarchy from UI Builder

1. Open the UXML asset in UI Builder and select exactly one target element.
2. Open Tools > D.A. Assets in the main Unity menu.
3. Choose UITK Linker: Copy element name hierarchy, Copy element index hierarchy, Copy element index + name hierarchy, or Copy element guid hierarchy.
4. Paste the serialized clipboard value into the linker's Names or Guids array field in the Inspector.

The index + name command stores both values for readability, but runtime lookup still prioritizes Index whenever it is not -1.

Persist GUID values

Use ULB *G elements in UXML, save the UXML asset, and verify that each guid attribute remains serialized. A GUID generated only in memory is not a stable locator.

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:ulb="DA_Assets.ULB">
    <ulb:ButtonG
        name="save-button"
        guid="9c7f1231e0aa438687d8804d63053783"
        text="Save" />
</ui:UXML>

Access the linked element

using System.Collections;
using DA_Assets.ULB;
using UnityEngine;

public sealed class SaveView : MonoBehaviour
{
    [SerializeField] private UitkButton saveButton;

    private IEnumerator Start()
    {
        yield return null;
        saveButton.Element.clicked += Save;
    }

    private void Save()
    {
    }
}

Element and E return the same typed reference.

Choose a mode

• Name: simplest setup; requires a stable unique name.
• IndexNames: follows one branch efficiently; update it after reordering or renaming hierarchy segments.
• Guid: resilient to parent moves; performs a recursive descendant search.
• Guids: most selective GUID lookup; update it after changing the GUID parent chain.