WebXR Layers API

The WebXR Layers API extends WebXR with separate composition layers for immersive sessions. An application can submit a rendered 3D scene alongside panels, curved surfaces or environment images, which the XR compositor combines for presentation.

Reviewed 21 October 2026. August 2026 Working Draft, layer types, session features, resource lifetime and implementation limits About review dates.

As of 21 October 2026, WebXR Layers API Level 1 was a W3C Working Draft dated 11 August 2026. The Immersive Web Working Group published its First Public Working Draft on 3 December 2020. It had not reached W3C Recommendation status.

Rendering model

In the core WebXR rendering path, an XRWebGLLayer connects an XR session to a WebGL context. It supplies a framebuffer and the viewport for each view, allowing the application to render the views into the appropriate portions of that framebuffer. With composition layers, an application can instead keep some imagery separate from this eye buffer. Meta's implementation guide uses a skybox, video and interactive foreground as an example: the compositor handles the background and video separately while WebGL renders the changing foreground.

This separation can avoid sampling an image into the eye buffer and then sampling the result again during composition. A static background can remain available to the compositor without being redrawn by the application for every display frame. These are reasons to use layers for high-resolution imagery and text; the savings depend on the content and rendering path. Separate resolutions allow a detailed text panel alongside a lower-resolution main scene. The explainer describes potential improvements to judder and latency through compositor reprojection, rather than a fixed performance result for every application.

Layer types

XRWebGLBinding creates GPU-backed layers for an XR session and WebGL context. Its creation methods cover five composition-layer types.

Interface	Presentation
XRProjectionLayer	Fills the observer's view with application-rendered imagery. Unlike a positioned panel, it has no associated XRSpace.
XRQuadLayer	A flat rectangle positioned and oriented in 3D space. It has no thickness, and only its front is visible.
XRCylinderLayer	A curved rectangular surface.
XREquirectLayer	Maps equirectangular imagery onto the inside of a sphere.
XRCubeLayer	Uses a cubemap projected onto the inside faces of a cube.

A quad's space establishes its spatial relationship to the environment, and its transform supplies an offset and orientation within that space. Width and height describe its physical size in meters, separately from the resolution of its image. This distinguishes the placement and dimensions of a virtual panel from the number of pixels used to draw it.

Session setup and rendering

The August 2026 draft restricts layers to immersive-vr and immersive-ar sessions; inline sessions cannot use them. Non-projection composition layers require the layers feature to be enabled through the session's requiredFeatures or optionalFeatures request. A single projection layer can be used without that feature; submitting more than one layer still requires it.

After creating the layers, the application passes an ordered layers array to XRSession.updateRenderState(). The update is scheduled for a subsequent frame. This replaces the session's baseLayer, which then reports null; supplying both properties in one update is rejected. The array normally specifies back-to-front composition, so a later entry can cover an earlier one. Duplicate layer instances are rejected.

Rendering uses the binding to obtain the appropriate image resources. getViewSubImage() supplies a projection layer's render target for an XRView, while getSubImage() serves other composition layers. The returned subimage identifies the texture and viewport. Texture-array rendering also uses an image index to select the array slice. These textures have restricted access and lifetime within XR frame processing; they are not ordinary application-owned textures that can be read or used at arbitrary times.

Video layers

XRMediaBinding creates quad, cylinder and equirectangular layers from an HTMLVideoElement. The layer displays the video's frames. It does not include the video's playback controls, which need a separate interface. Playback still uses the video element's normal methods. The layer layout can identify stereoscopic imagery packed side by side or top to bottom, allowing the appropriate portion to reach each eye.

This provides a route for presenting 360-degree video without manually copying each decoded video frame into the application's scene texture. Meta documents media layers alongside its compositor-backed WebXR layers implementation.

Redrawing, ordering and resource limits

The shared XRCompositionLayer interface provides properties such as texture-alpha blending, layout and needsRedraw. The latter signals that content needs rendering in the next frame. Its destroy() method releases underlying layer attachments. A quad can also receive a redraw event when resources are lost or the compositor can no longer reproject its image. Static content therefore still needs a path for restoring its imagery.

Array ordering does not automatically give separately submitted surfaces the same occlusion behavior as objects rendered together. The August 2026 draft adds the optional depth-sorted-layers feature for depth ordering of projection, quad and cylinder layers. Other layer types retain array ordering. The browser may limit layer counts and pixel allocations, including for privacy reasons.

Implementation and fallback

Availability must be checked for the target browser and device. MDN marks the WebGL and media binding interfaces as experimental and of limited availability, and documents secure-context requirements. The draft's mandatory projection-layer behavior describes conforming implementations of the module; it does not establish that every browser with WebXR implements the module.

The Immersive Web project's WebXR Layers Polyfill implements layers in JavaScript and WebGL. It renders their contents into an internal baseLayer, which is then presented through the existing WebXR path. This offers API emulation rather than a separate native compositor path. Its documented omissions include non-projection onredraw events, mip-level handling and secondary projection views. Applications therefore need to distinguish API availability, supported layer types and the capabilities of the actual rendering implementation.