# VisualElementReference

> Represents a reference to a VisualElement in a PanelRenderer.

## Definition

* **Type:** Class
* **Namespace:** [UnityEngine.UIElements](/engine/6000.7/script-reference/unityengine/uielements.md)
* **Assembly:** UnityEngine.UIElementsModule
* **Implements:** [IEquatable\<VisualElementReference>](https://learn.microsoft.com/dotnet/api/system.iequatable-1), [IDisposable](https://learn.microsoft.com/dotnet/api/system.idisposable)

```csharp
public class VisualElementReference : IEquatable<VisualElementReference>, IDisposable
```

## Remarks

This example shows how to use VisualElementReference to reference an element in a UXML file that is loaded by a `PanelRenderer`.

```csharp
using UnityEngine;
using UnityEngine.UIElements;

public class VisualElementReference_Example : MonoBehaviour
{
    // Set via the inspector
    public VisualElementReference elementReference = new VisualElementReference();
    public Color customColor = Color.red;

    void Start()
    {
        elementReference.RegisterReferenceResolvedCallback(SetupElementBackground);
    }

    void SetupElementBackground(VisualElement ve)
    {
        ve.style.backgroundColor = customColor;
    }
}
```

The following example configures paths to reference elements in a nested UXML structure. Root UXML:

```csharp
<ui:UXML xmlns:ui="UnityEngine.UIElements" editor-extension-mode="False">
    <ui:Template name="VisualElementReference_ExampleTemplate" src="./VisualElementReference_ExampleTemplate.uxml"/>
    <ui:VisualElement name="my-element" authoring-id="123"/>
    <ui:Button text="Button" name="my-button" authoring-id="-5"/>
    <ui:Instance template="VisualElementReference_ExampleTemplate" name="instance1" authoring-id="1"/>
    <ui:Instance template="VisualElementReference_ExampleTemplate" name="instance2" authoring-id="2"/>
</ui:UXML>
```

Template UXML:

```csharp
<ui:UXML xmlns:ui="UnityEngine.UIElements" editor-extension-mode="False">
    <ui:VisualElement name="template-element" authoring-id="1"/>
    <ui:Button text="Button" name="template-button" authoring-id="101"/>
</ui:UXML>
```

```csharp
using UnityEngine;
using UnityEngine.UIElements;

public class VisualElementReference_ExampleNested : MonoBehaviour
{
    public VisualElementReference<Button> templateInstance1Button = new VisualElementReference<Button>();
    public VisualElementReference elementReference = new VisualElementReference();

    void Start()
    {
        var pr = GetComponent<PanelRenderer>();

        // 101 is the AuthoringId of the Button inside the template instance with AuthoringId 1
        templateInstance1Button.SetReference(pr, new AuthoringIdPath(1, 101));
        templateInstance1Button.RegisterReferenceResolvedCallback(SetupButtonReference);
        templateInstance1Button.RegisterReferenceUnloadedCallback(TeardownButtonReference);

        // 123 is the AuthoringId of a VisualElement in the root UXML file
        elementReference.SetReference(pr, new AuthoringIdPath(123));
        elementReference.RegisterReferenceResolvedCallback(SetupElementReference);
    }

    void SetupButtonReference(Button button)
    {
        button.clicked += OnButtonClick;
    }

    void TeardownButtonReference(Button button)
    {
        button.clicked -= OnButtonClick;
    }

    void OnButtonClick()
    {
        Debug.Log("Button inside template instance clicked!");
    }

    void SetupElementReference(VisualElement ve)
    {
        ve.Add(new Label { text = "Element Reference Resolved!" });
    }
}
```

## Constructors

| Constructor                                                                                                                                                                                                                                          | Description                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [VisualElementReference()](/engine/6000.7/script-reference/unityengine/uielements/visualelementreference/ctor.md#visualelementreference\(\))                                                                                                         | Creates a new empty VisualElementReference.                                   |
| [VisualElementReference(UnityEngine.UIElements.PanelRenderer,UnityEngine.UIElements.AuthoringIdPath)](/engine/6000.7/script-reference/unityengine/uielements/visualelementreference/ctor.md#visualelementreference\(panelrenderer-authoringidpath\)) | Creates a new VisualElementReference pointing to the given renderer and path. |

## Properties

| Property                                                                                                        | Description                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [authoringPath](/engine/6000.7/script-reference/unityengine/uielements/visualelementreference/authoringpath.md) | The path to the referenced element. [VisualElementReference.SetReference](/engine/6000.7/script-reference/unityengine/uielements/visualelementreference/setreference.md)         |
| [panelRenderer](/engine/6000.7/script-reference/unityengine/uielements/visualelementreference/panelrenderer.md) | The provider used to resolve the reference. [VisualElementReference.SetReference](/engine/6000.7/script-reference/unityengine/uielements/visualelementreference/setreference.md) |

## Methods

| Method                                                                                                                                                      | Description                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Equals](/engine/6000.7/script-reference/unityengine/uielements/visualelementreference/equals.md)                                                           | Indicates whether the current object is equal to another element reference.                                                                                                                                                                        |
| [RegisterReferenceResolvedCallback](/engine/6000.7/script-reference/unityengine/uielements/visualelementreference/registerreferenceresolvedcallback.md)     | Registers a callback for when the reference is resolved from the document. When you register a callback, if the reference is already resolved, the callback is immediately invoked.                                                                |
| [RegisterReferenceUnloadedCallback](/engine/6000.7/script-reference/unityengine/uielements/visualelementreference/registerreferenceunloadedcallback.md)     | Registers a callback for when the referenced object is unloaded. This occurs when the document is destroyed, such as when a live reload occurs after the VisualTreeAsset changes. At this point, all references are invalid and should be cleared. |
| [SetReference](/engine/6000.7/script-reference/unityengine/uielements/visualelementreference/setreference.md)                                               | Sets the reference to point to the given document and path.                                                                                                                                                                                        |
| [UnregisterReferenceResolvedCallback](/engine/6000.7/script-reference/unityengine/uielements/visualelementreference/unregisterreferenceresolvedcallback.md) | Unregisters a callback for when the reference is resolved from the document.                                                                                                                                                                       |
| [UnregisterReferenceUnloadedCallback](/engine/6000.7/script-reference/unityengine/uielements/visualelementreference/unregisterreferenceunloadedcallback.md) | Unregisters a callback for when the referenced object is unloaded.                                                                                                                                                                                 |