Develop

UIKitDocument (DOM-like API)

Updated: Sep 4, 2026

UIKitDocument wraps an instantiated UIKit component tree in a Three.js Group. It provides element queries, sizing support used by ScreenSpace, and document cleanup.

Obtain the document

For a manifest asset created in code, keep the returned UIKitMLAsset.

const panel = await world.assets.instantiate<UIKitMLAsset>('main-menu');
const entity = world.createTransformEntity(panel);
const document = panel.document;

For a panel placed by a native scene, look up the asset by stable scene node ID.

const panel = world.requireSceneObject<UIKitMLAsset>('main-menu-panel');
const document = panel.document;

PanelUI and PanelDocument provide compatibility for panels loaded from a raw URL. Manifest-backed UIKitMLAsset is the primary path for new content.

Query elements

const startButton = document.requireElementById('start');
const optionalTitle = document.getElementById('title');
const rows = document.getElementsByClassName('row');
const firstLabel = document.querySelector('#menu .label');
const allLabels = document.querySelectorAll('#menu .label');

getElementById() returns the element or null.

requireElementById() returns the element or throws when the ID is absent.

Class and selector queries search descendants of the document root.

Supported selectors include IDs, classes, and descendant combinations.

Cache elements that are used every frame instead of repeating a deep query.

Handle events and classes

const startButton = panel.requireElementById('start');

startButton.addEventListener('click', startExperience);
startButton.classList.add('ready');
startButton.classList.remove('disabled');

The panel’s owning entity must have RayInteractable for browser-pointer and XR-ray input, PokeInteractable for touch input, or both before IWSDK can dispatch the corresponding events into the document.

IWSDK forwards configured pointer events to the UIKit tree and applies hover, active, and focus state.

Control world-space size

UIKit layout dimensions are centimeters. For a normal world-space panel, use the owning entity’s transform as the scale authority.

entity.object3D!.scale.setScalar(0.25);

UIKitDocument.setTargetDimensions(widthMeters, heightMeters) remains available for low-level fitting. ScreenSpaceUISystem uses target dimensions while the document is in browser screen space and clears them when the document returns to XR world space.

ScreenSpace behavior

Outside XR, ScreenSpaceUISystem temporarily moves the document under world.camera. It does not move the host entity. While this mode is active, the host transform and visibility do not control the document.

When XR begins, the document returns to its host object and the authored world transform becomes active.

See HUD placement for placement choices.

Lifecycle

Manifest asset instances are disposed with their owning entity. Code that calls loadUIKitMLAsset() directly can call dispose() explicitly.

standalonePanel.dispose();

After disposal, discard cached element references. A legacy PanelUI host must be created with world.createTransformEntity() because the document needs an object3D parent.

See UIKitML for authoring and asset registration.