# XrDomOverlay

Class · category: XR

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/framework/xr/xr-dom-overlay.js#L30

DOM Overlay provides the ability to use DOM elements as an overlay in a WebXR AR session. It
requires that the root DOM element is provided for session start. That way, input source
`select` events are first tested against DOM Elements and then propagated down to the XR
Session. If this propagation is not desirable, use the `beforexrselect` event on a DOM element
and the `preventDefault` function to stop propagation.

```javascript
app.xr.domOverlay.root = element;
app.xr.start(camera, XRTYPE_AR, XRSPACE_LOCALFLOOR);
```

```javascript
// Disable input source firing `select` event when some descendant element of DOM overlay root
// is touched/clicked. This is useful when the user interacts with UI elements and there should
// not be `select` events behind UI.
someElement.addEventListener('beforexrselect', (evt) => {
    evt.preventDefault();
});
```

## Accessors

### available

```ts
get available(): boolean
```

True if DOM Overlay is available. This information becomes available only when the session has
started and a valid root DOM element has been provided.

### root

```ts
get root(): Element | null
set root(value: Element | null)
```

Gets the DOM element to be used as the root for DOM Overlay.

### state

```ts
get state(): "screen" | "floating" | "head-locked" | null
```

State of the DOM Overlay, which defines how the root DOM element is rendered. Can be:

- `screen` - indicates that the DOM element is covering the whole physical screen, matching
XR viewports.
- `floating` - indicates that the underlying platform renders the DOM element as floating in
space, which can move during the WebXR session or allow the application to move the element.
- `head-locked` - indicates that the DOM element follows the user's head movement
consistently, appearing similar to a helmet heads-up display.

### supported

```ts
get supported(): boolean
```

True if DOM Overlay is supported.