# 8. UI Toolkit for VR
Part of [[UI Toolkit and Diegetic UI]]. Requires Unity 6.3 LTS (6000.3.27f2) and newer. Previous: [[7.UI Toolkit Pitfalls and Performance]]. Related: [[Meta Quest 2]], [[7.Quest 2 Worked Example Room]].
> [!important] Version requirement
> Unity 6.3 LTS (6000.3.27f2) and newer. UI Toolkit world-space support in XRI needs Unity 6.2+ and XRI 3.2.0+ at minimum; XRI 3.4+ is recommended (adds `XRRayInteractor` and z-depth poke support; 3.5.0+ adds thumbstick scrolling of scroll views).
> [!note] Scripts are uncompiled
> The scripts here were written without an editor. Treat the first compile as part of the tutorial.
So far this tutorial series put UI Toolkit on screens, on meshes via RenderTexture ([[6.Diegetic Terminal and Wrist Display]]) and inside the world. This note puts it in **VR**, where the pointer is a ray or a fingertip instead of a mouse.
## 8.1 What is supported
| Question | Answer | Source |
|---|---|---|
| Can UI Toolkit render in world space? | Yes. `PanelSettings` has a **World Space** render mode (Unity 6.2+). | [XRI + UI Toolkit](https://docs.unity3d.com/Packages/
[email protected]/manual/ui-world-space-ui-toolkit-support.html) |
| Do XRI interactors drive it? | Yes. Ray (XR Ray Interactor, Near-Far Interactor) and poke (`XRPokeInteractor`) via `XRUIToolkitManager`; hands and controllers. | same |
| Minimum versions | Unity 6.2, XRI 3.2.0. `XRRayInteractor` support was added in XRI 3.4.0 per the XRI changelog. | same, [changelog](https://docs.unity3d.com/Packages/
[email protected]/changelog/CHANGELOG.html) |
| Text input | System/software keyboard only; on Quest enable **Enable System Keyboard** in Meta Quest Support (OpenXR 1.17.0+ required by the XRI docs). | XRI docs |
| Scroll views | Drag-scroll needs Unity 6000.3.8f1 / 6000.4.0b9 / 6000.5.0a7 or newer; otherwise use the scroll bar handles or thumbstick (thumbstick scrolling of UI Toolkit scroll views needs XRI 3.5.0+). | XRI docs |
| Meta Interaction SDK (ISDK) | ISDK's UI integration is documented for **uGUI** (`PointableCanvas`). I found **no ISDK documentation for UI Toolkit panels**. Use the fallback in 8.6. | Meta ISDK docs **(absence of UI Toolkit docs is unverified)** |
| `PanelRenderer` (6000.5+ component) with XRI | Not used here: this series targets Unity 6.3 LTS, where `UIDocument` with a World Space Panel Settings asset is the path. Newer Unity docs mark `UIDocument` obsolete in favour of `PanelRenderer`; the XRI docs I read describe `UIDocument`, so XRI with `PanelRenderer` is **unverified**. | - |
Conclusion: with **XRI 3.x on OpenXR**, direct support is complete enough to build the Quest 2 panel in [[7.Quest 2 Worked Example Room]] without a fallback. With **Meta ISDK** or a **custom rig**, use the render-texture fallback.
## 8.2 Route A: XRI direct world-space panels (steps)
1. **Panel Settings.** Right-click in Project > **Create > UI Toolkit > Panel Settings Asset**. Set **Render Mode = World Space**.
2. **Collider mode** (also on Panel Settings, "Collider Update Mode"). The XRI docs list:
- **Keep existing colliders (if any)**: you add and size a collider yourself.
- **Match 2-D document rect**: UI Toolkit creates a flat collider. Poke still works but completes instantly (zero thickness, no depth animation).
- **Match 3-D bounding box**: gives depth along the poke axis, so poke depth animation works. Prefer this for poke.
3. **UI Document.** Create **GameObject > UI Toolkit > UI Document**. Assign the UXML as Source Asset and your Panel Settings.
4. **Scene components.**
- Add **XR UI Toolkit Manager** (`XRUIToolkitManager`) to one GameObject. It globally enables UI Toolkit support in XRI.
- Add a **Panel Input Configuration** component and set **Panel Input Redirection = No input redirection** (enum value Never) so the event system does not interfere.
- If you also use uGUI: keep an EventSystem with **XR UI Input Module** and **disable `bypassUIToolkitEvents`**.
5. **Ray**: that is all that is required for ray interaction once the collider exists.
6. **Poke** (finger or controller tip): add **XRSimpleInteractable** and **XRPokeFilter** to the panel object. Use USS `translate` on a `Button`/`Toggle`/`VisualElement` to set its resting z-depth. Nested children of z-depth elements can block poke (handled for Button and Toggle).
7. **Hover**: interactors implementing `IUIHoverInteractor` raise `UIHoverEnterEvent`/`UIHoverExitEvent` with the `VisualElement` and `UIDocument` in `UIHoverEventArgs`.
> [!warning] Order and collider traps from the XRI docs
> - The `UIDocument` component must exist **before** the interactable registers with the interaction manager.
> - `XRBaseInteractable` searches the GameObject and children for colliders. A nested UIDocument collider can be mistaken for the interactable's own collider. Assign interactable colliders manually, or set **Is Trigger** on the UI Document collider.
> - Match 2-D / 3-D colliders are created in `LateUpdate` after the first render; the XR UI Toolkit Manager registers them with the interactable automatically.
> - Changing Collider Update Mode at runtime is not supported.
> - In the editor over **Meta Horizon Link**, click the **Game view** once: UI Toolkit input is only redirected when the Game view has focus.
## 8.3 Script: setup diagnostics
Add this to the panel GameObject. It prints what is missing, so you do not have to hunt through the Inspector. It looks up XRI types **by name** so it still compiles if a namespace differs between XRI versions.
```csharp
using System.Linq;
using UnityEngine;
using UnityEngine.UIElements;
/// <summary>
/// Logs the common setup mistakes for an XRI world-space UI Toolkit panel.
/// Not compiled in an editor.
/// </summary>
[RequireComponent(typeof(UIDocument))]
public class XRUIToolkitPanelDiagnostics : MonoBehaviour
{
void Start()
{
var doc = GetComponent<UIDocument>();
int problems = 0;
if (doc.panelSettings == null)
{
Report("UIDocument has no Panel Settings asset."); problems++;
}
else if (doc.panelSettings.renderMode != PanelRenderMode.WorldSpace)
{
Report(