UI Document component

A UI Document component references a UXML document and a Panel Settings asset. It serves as a bridge between the SceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary and a UXML document.

Note: UI Document components have been deprecated in favor of the Panel Renderer component, which provides the same functionality and has better performance for features like world space UI and more. To migrate from a UI Document component to a Panel Renderer component, refer to [Migration to Panel Renderer].(#migration-to-panel-renderer).

Connect the UI to a panel

To connect a UI Document component to a panel, assign a Panel Settings asset to the UI Document component. The Panel Settings asset defines the panel in the Scene where the UI is rendered. The UI Document component uses this panel to render the UXML document it references.

Because the UI Document component has been deprecated, you can’t add the component to new GameObjects in the Unity Editor. Existing UI Document components in your project will continue to work, if they have already been assigned to a GameObjectThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary. You can configure them as needed:

• Panel Settings: The Panel Settings asset that renders the UI.
• Source Asset: The UXML document that contains the UI to display.
• Sort Order: The rendering order of the UI Document component. The lower the value, the earlier the UI Document component renders.

Lifecycle of UI Document components

Unity loads a UI Document component’s source UXML documents when it calls the OnEnable() method on the component. To ensure the visual treeAn object graph, made of lightweight nodes, that holds all the elements in a window or panel. It defines every UI you build with the UI Toolkit.
See in Glossary loads correctly, add logic to interact with the controls inside the OnEnable() method. This means your script must respond to OnEnable() and OnDisable() to safely reference visual elementsA node of a visual tree that instantiates or derives from the C# VisualElement class. You can style the look, define the behaviour, and display it on screen as part of the UI. More info
See in Glossary from your UXML documents.

A UI Document component clears its contents when it responds to the OnEnable() and OnDisable() methods. This approach removes UI elements that the UI Document won’t reuse soon and effectively clears the associated resources. Additionally, if a UI Document component isn’t assigned with a Panel Settings asset, it automatically clears its contents.

To hide a UI element that’s likely to be reused soon or needs to appear quickly to avoid an initialization penalty, set the display of the UIDocument.rootVisualElement to none. You can also use this to hide a UI element component that’s part of a larger UI hierarchy.

Migration to Panel Renderer

The Panel Renderer component has been introduced as a replacement for the UI Document component. It addresses several limitations of the UI Document component:

• Lifecycle management: UI Document’s direct rootVisualElement access made lifecycle control difficult, requiring workarounds that often failed or caused bugs. Panel Renderer uses UIReloaded callbacks for reliable UI reloading during OnEnable and LiveReload events.
• Native rendering: UI Document required hidden companion components for rendering, causing complications in Editor and Play modes. Panel Renderer is a native Renderer component that handles all UI rendering directly.
• Content persistence: UI Document destroys all content when disabled and recreates it when re-enabled, forcing users to implement non-standard caching solutions. Panel Renderer preserves UI content in memory when disabled.
• Clear naming: The UI Document component name conflicted with UXML UI Document assets, causing confusion. Panel Renderer aligns with existing terminology like PanelSettings.

While UI Document remains supported for existing projects, you are recommended to migrate to Panel Renderer.

Migrate Inspector-added UI Document components

If your project uses UI Document components that were added via 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 window, follow these steps to migrate them to Panel Renderer components:

1. Remove the UI Document component from the GameObject’s Inspector window.
2. Add a Panel Renderer component to the GameObject.
3. Assign the appropriate Panel Settings and UXML assets, and Sort Order to the Panel Renderer component.
4. If your C# MonoBehaviour used the following UI Document component initialization logic:

void OnEnable()
{
     var uiDocument = GetComponent<UIDocument>();
     myButton = uiDocument.rootVisualElement.Q<Button>();
}

Update it to:

void OnEnable()
{
     GetComponent<PanelRenderer>().RegisterUIReloadCallback(OnUIReload);
}
void OnDisable()
{
     GetComponent<PanelRenderer>().UnregisterUIReloadCallback(OnUIReload);
}
void OnUIReload(PanelRenderer renderer, VisualElement rootElement)
{
     myButton = rootElement.Q<Button>();
}

Migrate script-added UI Document components

If your script creates a UI Document component via AddComponent<UIDocument>(), replace it with AddComponent<PanelRenderer>().

Before:

var uiDocument = gameObject.AddComponent<UIDocument>();
uiDocument.sourceAsset = myUXMLAsset;

After:

var panelRenderer = gameObject.AddComponent<PanelRenderer>();
panelRenderer.sourceAsset = myUXMLAsset;

Additional resources

• Panel Renderer component