CSS :xr-overlay Pseudo-Class

CSS :xr-overlay Pseudo-Class

The CSS :xr-overlay pseudo-class selects the HTML element used as a DOM overlay during an immersive WebXR session. WebXR allows websites to create augmented reality (AR) and virtual reality (VR) experiences, while DOM overlays allow ordinary HTML content such as buttons, instructions, and menus to appear within those experiences. The :xr-overlay pseudo-class makes it possible to apply styles specifically while an element is serving as an active XR overlay.

:xr-overlay Syntax

:xr-overlay {
  property: value;
}

The pseudo-class matches the DOM overlay root element for the duration of an immersive WebXR session using that overlay.

Basic Example

:xr-overlay {
  color: #fff;
}

Applies white text to the active DOM overlay element. Descendant elements may inherit the text color.

ID Selector

#xr-ui:xr-overlay {
  color: #fff;
}

Style Overlay Controls

:xr-overlay button {
  background-color: #fff;
  color: #222;
}

Style Overlay Instructions

:xr-overlay .instructions {
  padding: 12px;
  background-color: rgba(0, 0, 0, 0.65);
  color: #fff;
}

No Arguments

The pseudo-class is written as :xr-overlay, without parentheses or arguments.

How :xr-overlay Works

The :xr-overlay pseudo-class becomes active when a supported WebXR session uses an HTML element as its DOM overlay.

Step 1 - Create an Overlay Element

<div id="xr-ui">
  <p>WebXR Controls</p>
  <button type="button">Close</button>
</div>

Step 2 - Request a WebXR Session

const overlay = document.getElementById("xr-ui");
const session = await navigator.xr.requestSession("immersive-ar", {
  requiredFeatures: ["dom-overlay"],
  domOverlay: { root: overlay }
});

This requests an immersive AR session that requires DOM overlay support. The request must be made in an appropriate secure, user-initiated context and can fail if the browser or device does not support the requested features.

Step 3 - Match the Active Overlay

#xr-ui:xr-overlay {
  color: #fff;
}

Step 4 - Style Overlay Content

#xr-ui:xr-overlay button {
  padding: 12px 18px;
  background-color: #fff;
  color: #222;
}

Step 5 - End the Session

When the immersive session ends, the element stops matching :xr-overlay and returns to its normal CSS state.

What Is WebXR?

WebXR is a browser API for creating immersive augmented reality and virtual reality experiences using web technologies.

Augmented Reality

Augmented reality combines computer-generated content with a view of the physical environment.

Virtual Reality

Virtual reality presents an immersive computer-generated environment.

WebXR Sessions

A WebXR session represents an active immersive or inline experience managed by the browser and a compatible device.

WebXR and CSS

WebXR manages the immersive experience, while CSS can style the HTML controls and instructions displayed through a DOM overlay.

Device Requirements

Immersive WebXR experiences require compatible browser and device capabilities. A standard desktop browser may not provide an immersive session.

DOM Overlays

A DOM overlay allows ordinary HTML elements to appear as a two-dimensional interface above the rendered immersive scene.

Overlay Root

<div id="xr-ui">
  <div class="instructions">Move your device to explore.</div>
  <button type="button">Exit Experience</button>
</div>

The #xr-ui element can serve as the overlay root, with its descendants displayed as part of the interface.

One Overlay Root

A WebXR DOM overlay session uses a single root element. That root can contain multiple HTML controls and other elements.

Overlay Content

Common overlay content includes buttons, instructions, menus, status indicators, and other interface elements.

Overlay Positioning

The browser applies special layout rules to the overlay root, including fixed positioning and viewport-sized dimensions.

Transparent Background

The overlay root has a transparent background by default, allowing the immersive scene to remain visible where descendant elements do not cover it.

Overlay Descendants

Descendant elements can use ordinary CSS for backgrounds, text colors, spacing, borders, and positioning.

Overlay Root vs. Descendants

The root element matches :xr-overlay. Its descendants do not automatically match that pseudo-class, but they can be selected using descendant selectors such as :xr-overlay button.

Requesting a WebXR Session

JavaScript is required to request an immersive WebXR session and specify the HTML element that will serve as its DOM overlay.

Required DOM Overlay

const overlay = document.getElementById("xr-ui");
const session = await navigator.xr.requestSession("immersive-ar", {
  requiredFeatures: ["dom-overlay"],
  domOverlay: { root: overlay }
});

When DOM overlay support is required, the session request fails if the browser cannot provide that feature.

Optional DOM Overlay

const overlay = document.getElementById("xr-ui");
const session = await navigator.xr.requestSession("immersive-ar", {
  optionalFeatures: ["dom-overlay"],
  domOverlay: { root: overlay }
});

When the feature is optional, the session may start without a DOM overlay. Check session.domOverlayState before assuming the overlay is available.

Check for the WebXR API

if ("xr" in navigator) {
  console.log("WebXR API is available.");
} else {
  console.log("WebXR API is unavailable.");
}

API availability alone does not guarantee that an immersive session or DOM overlay is supported.

User Interaction

Immersive session requests generally require a user action, such as clicking a button.

Secure Context

WebXR is restricted to secure contexts, normally pages served over HTTPS or qualifying local development origins.

Session Rendering

A complete immersive application also needs to establish the appropriate XR rendering setup. Requesting a session alone does not render a three-dimensional scene.

Styling an XR Overlay

The :xr-overlay pseudo-class allows styles to apply specifically during an active immersive session.

Text Color

:xr-overlay {
  color: #fff;
}

Overlay Panel

:xr-overlay .panel {
  padding: 16px;
  background-color: rgba(0, 0, 0, 0.7);
  color: #fff;
  border-radius: 8px;
}

Overlay Buttons

:xr-overlay button {
  padding: 12px 18px;
  background-color: #fff;
  color: #222;
  border: 0;
  border-radius: 6px;
}

Show XR-Only Content

.xr-only {
  display: none;
}
:xr-overlay .xr-only {
  display: block;
}

Hide Ordinary Page Content

:xr-overlay .page-only {
  display: none;
}

Browser-Controlled Root Styles

The WebXR DOM Overlays specification defines important user-agent styles for the overlay root, including fixed positioning, dimensions, and a transparent background. Several of these declarations use !important, so author styles cannot override them through ordinary rules.

Backdrop Filters

Backdrop filters applied to the overlay or its descendants do not filter the underlying AR camera image or the immersive scene rendered by WebXR.

:xr-overlay vs. :fullscreen

Both pseudo-classes identify elements displayed in special presentation modes, but they represent different browser features.

XR Overlay Styling

:xr-overlay .controls {
  color: #fff;
}

Fullscreen Styling

:fullscreen .controls {
  color: #fff;
}

Independent Features

Browsers may implement WebXR DOM overlays using fullscreen-related mechanisms, but the specification does not require :xr-overlay and :fullscreen to match the same element.

Choosing the Correct Selector

Use :xr-overlay for active WebXR DOM overlays and :fullscreen for elements presented through the Fullscreen API.

Checking Overlay State

The WebXR API provides information about whether a DOM overlay is enabled for an immersive session.

Read the Overlay State

if (session.domOverlayState) {
  console.log(session.domOverlayState.type);
} else {
  console.log("DOM overlay is not enabled.");
}

Overlay Display Types

Check Selector Support

const supported = CSS.supports("selector(:xr-overlay)");
console.log(supported);

This checks whether the browser recognizes the CSS selector. It does not establish that the device supports an immersive WebXR session.

Check an Active Element

const overlay = document.getElementById("xr-ui");
console.log(overlay.matches(":xr-overlay"));

This checks whether the element currently matches the selector in a browser that supports it.

Session State vs. CSS State

The domOverlayState property provides information about the active overlay, while :xr-overlay provides a CSS selector for styling its root element.

:xr-overlay Specificity

The :xr-overlay pseudo-class contributes a specificity of 0-1-0, like other standard pseudo-classes.

Specificity Examples

Specificity Example

#xr-ui .panel {
  color: #333;
}
#xr-ui:xr-overlay .panel {
  color: #fff;
}

The second selector has higher specificity and changes the panel text color during the active XR overlay session, assuming other cascade factors are equal.

Limitations

The :xr-overlay pseudo-class depends on an active WebXR DOM overlay and cannot create an immersive session by itself.

Requires WebXR Support

The browser and device must support the necessary WebXR capabilities.

Requires an Active Overlay

The selector does not match an ordinary HTML element simply because it has an ID or class associated with XR.

Cannot Start a Session

CSS cannot request or start a WebXR session. JavaScript must use the WebXR API.

Not a Fullscreen Replacement

The selector is specific to WebXR DOM overlays rather than general fullscreen content.

Browser-Controlled Layout

Browsers enforce special styles on the overlay root, including fixed positioning and transparent-background behavior.

No Ordinary Browser Simulation

A regular browser window or iframe cannot reproduce the active selector state without a supported immersive WebXR session.

Limited Browser Availability

Some major browsers do not support the feature. Applications should provide appropriate fallbacks for unsupported devices and browsers.

Accessibility

WebXR overlays should provide clear, accessible controls that remain usable during an immersive experience.

Readable Text

Choose text and panel colors that provide adequate contrast against the changing immersive background.

Visible Controls

Buttons and menus should be large enough to interact with comfortably on supported devices.

Keyboard and Input Support

Use semantic HTML controls and preserve supported keyboard, pointer, and assistive technology interactions.

Clear Exit Controls

Provide an understandable way to leave the immersive experience.

Avoid Color-Only Information

Use readable text or other indicators rather than relying entirely on color.

Fallback Content

Provide useful instructions or alternative content when immersive WebXR is unavailable.

Screen Reader Considerations

The :xr-overlay pseudo-class only changes CSS matching. It does not automatically create accessible names, descriptions, or announcements.

Best Practices

• Use :xr-overlay only for styling an active WebXR DOM overlay.
• Keep the overlay root and its descendant controls clearly organized.
• Use semantic HTML buttons and other accessible interface elements.
• Provide sufficient contrast against immersive scene backgrounds.
• Do not rely on CSS to start or control a WebXR session.
• Check WebXR and DOM overlay support before requesting a session.
• Handle rejected session requests gracefully.
• Remember that browser-defined overlay root styles may override author declarations.
• Provide fallback content for browsers and devices without WebXR support.
• Test the complete experience on compatible immersive hardware.

:xr-overlay Example

This example shows an HTML overlay with an instruction panel and a button. The panel can be viewed in a normal browser, but the :xr-overlay styles only activate when the element becomes the root of an immersive WebXR DOM overlay. A normal iframe cannot activate this state.

HTML

<div id="xr-ui">
  <div class="xr-panel">
    <p>WebXR Overlay Example</p>
    <p class="xr-instructions">These controls can appear over an immersive XR scene.</p>
    <button type="button">Example Control</button>
  </div>
</div>

CSS

#xr-ui {
  padding: 10px;
}
#xr-ui .xr-panel {
  padding: 12px;
  border: 2px solid #006699;
  border-radius: 6px;
}
#xr-ui .xr-panel p {
  margin: 0 0 10px;
}
#xr-ui button {
  padding: 8px 12px;
  cursor: pointer;
}
#xr-ui:xr-overlay .xr-panel {
  background-color: rgba(0, 0, 0, 0.7);
  color: #fff;
  border-color: #fff;
}
#xr-ui:xr-overlay button {
  background-color: #fff;
  color: #222;
  border: 0;
}

Browser Result

Play in Editor

Note: The browser result displays the normal HTML styles. The immersive overlay styles require a supported WebXR session and cannot be demonstrated by this static example. The button is illustrative and does not start a WebXR session.

Browser Support

Baseline: Limited availability. The experimental :xr-overlay pseudo-class is supported in Chromium-based browsers such as Chrome and Edge, but is not supported in Firefox or Safari. Actual use also requires compatible WebXR hardware and DOM overlay support.

For current compatibility information, visit Can I Use? .

Specifications

The :xr-overlay pseudo-class is defined in the WebXR DOM Overlays Module. It matches the designated overlay element for the duration of an immersive WebXR session using a DOM overlay.

WebXR DOM Overlays Module - CSS Pseudo-Class