# AppElement

Class · extends [`AsyncElement`](https://api.playcanvas.com/web-components/classes/AsyncElement.md) · category: Application

Source: https://github.com/playcanvas/web-components/blob/252f001881302c266c8d727044408c32be2bb5e7/src/app.ts#L139

The AppElement interface provides properties and methods for manipulating
[`<pc-app>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-app/) elements.
The AppElement interface also inherits the properties and methods of the
[HTMLElement](https://developer.mozilla.org/docs/Web/API/HTMLElement) interface.

The element is sized like a replaced element such as `<video>`: a block-level box that the
page's CSS controls, 300x150 by default. The application's canvas always fills the element,
and the drawing buffer resolution follows the element's size (capped by `max-pixel-ratio`),
tracked live via a ResizeObserver — so the element can be embedded at any size, resized by
its container, or made fullscreen with ordinary CSS such as `width: 100vw; height: 100dvh`.

Pointer input over the canvas is hit-tested against the scene and dispatched as pointer events
on the entity elements under the pointer, where they behave like the DOM's own pointer events;
`picking` controls when that happens. The canvas keeps receiving its native events too, so a
listener on this element sees both kinds - `event.target` tells them apart.

**elementSummary** The `<pc-app>` element creates a PlayCanvas application and the canvas it renders
into, and is the root of every scene. It holds the `<pc-asset>`, `<pc-material>`, `<pc-wasm>` and
`<pc-scene>` elements, loads the area light lookup tables from one of its assets, sets how
fast the application and its physics simulation run, and the page's CSS sizes it, as it would a
`<video>`.

**fires** progress - Fired while the application preloads its assets. `loaded` and
`total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
not bubble.

**fires** error - Fired when the application cannot boot because no graphics device
could be created (for example, a browser with WebGL disabled). `message` names the requested
backends and `error` holds the underlying failure. The element never becomes ready
and `app` stays `null` — listen for this event to show a fallback UI. Removing the element and
re-inserting it retries the boot with its current attributes. Does not bubble.

## Accessors

### alpha

```ts
get alpha(): boolean
set alpha(value: boolean)
```

Gets whether the frame buffer has an alpha channel.

### antialias

```ts
get antialias(): boolean
set antialias(value: boolean)
```

Gets whether the frame buffer is anti-aliased.

### app

```ts
get app(): AppBase | null
```

The PlayCanvas application instance. `null` until the element is ready, and again once it
has been removed from the document — await [whenReady](https://api.playcanvas.com/web-components/functions/whenReady.md) or the element's `ready()`
promise before accessing it.

### areaLightLuts

```ts
get areaLightLuts(): string
set areaLightLuts(value: string)
```

Gets the id of the `<pc-asset>` holding the area light lookup tables, whose loading also
enables area lights for the application.

### backend

```ts
get backend(): "webgpu" | "webgl2" | "null"
set backend(value: "webgpu" | "webgl2" | "null")
```

Gets the graphics backend.

### depthBuffer

```ts
get depthBuffer(): boolean
set depthBuffer(value: boolean)
```

Gets whether the frame buffer has a depth buffer.

### devtools

```ts
get devtools(): boolean
set devtools(value: boolean)
```

Gets whether the application announces itself to developer tools, such as the PlayCanvas
Inspector browser extension, so they can find and inspect it.

### loadingBar

```ts
get loadingBar(): boolean
set loadingBar(value: boolean)
```

Gets whether the application shows its built-in loading bar while it boots and preloads
its assets.

### loadProgress

```ts
get loadProgress(): number
```

The asset preload progress of the application, as a fraction from 0 to 1. It is 0 until
preloading begins (and again once the element has been removed from the document), and 1
once preloading has finished — including when there was nothing to preload. Read this to
initialize a loading UI; subsequent updates arrive via the `progress` event.

### maxPixelRatio

```ts
get maxPixelRatio(): number
set maxPixelRatio(value: number)
```

Gets the cap on the pixel ratio the application renders at.

### physicsTimeScale

```ts
get physicsTimeScale(): number
set physicsTimeScale(value: number)
```

Gets the scale on the time the physics simulation advances by each frame, applied on top of
`time-scale`: 0 pauses physics alone while the rest of the application keeps running.

### picking

```ts
get picking(): "auto" | "always" | "none"
set picking(value: "auto" | "always" | "none")
```

Gets how the application decides whether to pick the scene under the pointer, which it
does to dispatch pointer events on entity elements: `auto` picks for an event type while a
listener for it is registered on an entity element or `<pc-scene>`, `always` for every
pointer event, and `none` never.

### stencilBuffer

```ts
get stencilBuffer(): boolean
set stencilBuffer(value: boolean)
```

Gets whether the frame buffer has a stencil buffer.

### timeScale

```ts
get timeScale(): number
set timeScale(value: number)
```

Gets the scale on the time the application advances by each frame. Scripts, animation and
physics all advance by the scaled time, so 0 pauses all three together.

### withCredentials

```ts
get withCredentials(): boolean
set withCredentials(value: boolean)
```

Gets whether asset requests send credentials (cookies and HTTP authentication) to other
origins, which applies to every application on the page. Once the application has booted,
this reports the engine's page-wide setting - which another `<pc-app>` may have switched on -
rather than this element's own attribute.

## Methods

### elementFromEntity

```ts
elementFromEntity(entity: Entity): EntityBaseElement | null
```

Returns the `<pc-entity>`, `<pc-model>` or `<pc-node>` element whose backing entity is
`entity`, or `null` if the entity is not fronted by an element of this application - for
example, an unbound node inside a model's instantiated hierarchy, or an entity created
through the engine API.

**Parameters**

- `entity` (`Entity`): The entity to look up.

**Returns** [`EntityBaseElement`](https://api.playcanvas.com/web-components/classes/EntityBaseElement.md) `| null`: The element fronting the entity, or `null`.

## Inherited from [AsyncElement](https://api.playcanvas.com/web-components/classes/AsyncElement.md)

- `get closestApp(): AppElement | null`
- `protected _onReady(): void`
- `protected _resetReady(): void`
- `ready(): Promise<AppElement>`

## Inherited from [EntityOwnerElement](https://api.playcanvas.com/web-components/classes/EntityOwnerElement.md)

- `get closestEntity(): EntityBaseElement | null`