Skip to content

toggleOverlay proposal #1439

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cabanier wants to merge 4 commits into
base: main
Choose a base branch
from
Open

toggleOverlay proposal #1439

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
97a3fa7
toggleOverlay proposal
cabanier Jun 29, 2026
aafde89
Clarify browser overlay toggle requirements
cabanier Jul 2, 2026
d4dba6a
address comments from 7/7/2026 meeting
cabanier Jul 7, 2026
708a0cd
adddress review comment
cabanier Jul 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -643,6 +643,7 @@ enum XRVisibilityState {
undefined updateRenderState(optional XRRenderStateInit state = {});
Promise<undefined> updateTargetFrameRate(float rate);
[NewObject] Promise<XRReferenceSpace> requestReferenceSpace(XRReferenceSpaceType type);
undefined toggleOverlay();

@alcooper91 alcooper91 Jul 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this might need to be a promise and we update the algorithm to reject if it's still changing/pending. I'm looking into if we could implement this, and even if we have a path that's not the suspend/resume session bit, I think it's going to be async for us.


unsigned long requestAnimationFrame(XRFrameRequestCallback callback);
undefined cancelAnimationFrame(unsigned long handle);
Expand All @@ -669,10 +670,37 @@ Each {{XRSession}} has an <dfn for=XRSession>animation frame</dfn>, which is an

Each {{XRSession}} has a <dfn for=XRSession>set of granted features</dfn>, which is a [=/set=] of {{DOMString}}s corresponding to the [=feature descriptors=] that have been granted to the {{XRSession}}.

Each {{XRSession}} has a <dfn for="XRSession">browser overlay shown</dfn> boolean, initially `false`, that indicates if the user agent is showing a browser overlay over the session.

The <dfn attribute for="XRSession">enabledFeatures</dfn> attribute returns the features in the [=XRSession/set of granted features=] as a new array of {{DOMString}}s.

The <dfn attribute for="XRSession">isSystemKeyboardSupported</dfn> attribute indicates that the {{XRSystem}} has the ability to display the system keyboard while the {{XRSession}} is active. If {{XRSession/isSystemKeyboardSupported}} is <code>true</code>, Web APIs that would trigger the overlay keyboard (such as [=focus=]) will show the system keyboard. The {{XRSession}} MUST set the [=visibility state=] of the {{XRSession}} to {{XRVisibilityState/"visible-blurred"}} while the keyboard is shown.

A <dfn>browser overlay</dfn> is user agent UI that displays the non-immersive browser interface over an [=immersive session=]. The user agent controls the size, position, appearance, and available controls of the [=browser overlay=].
Comment thread
cabanier marked this conversation as resolved.

<div class="algorithm" data-algorithm="toggle-overlay">

The <dfn method for="XRSession">toggleOverlay()</dfn> method requests that the user agent toggle whether a [=browser overlay=] is shown over an [=immersive session=]. When invoked, it MUST run the following steps:

1. Let |session| be [=this=].
1. If |session|'s [=XRSession/ended=] value is `true`, throw an "{{InvalidStateError}}" {{DOMException}} and abort these steps.
1. If |session| is not an [=immersive session=], throw a "{{NotSupportedError}}" {{DOMException}} and abort these steps.

@alcooper91 alcooper91 Jul 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NIT: I think redundant with the line that this feature shouldn't ever be granted to non-immersive sessions above?

@cabanier cabanier Jul 9, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is that listed somewhere else in this algorithm?

@alcooper91 alcooper91 Jul 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not in this one, but it's in the spec text you have about when the feature should be granted. I don't think we have algorithms for enabling most of those features though. I'm fine with leaving this line in but just wanted to raise the potential (IMO) redundancy

1. If |session|'s [=XRSession/browser overlay shown=] boolean is `true`, run the following steps:
1. Hide the [=browser overlay=] shown over |session|.
1. Set |session|'s [=XRSession/browser overlay shown=] boolean to `false`.
1. If no other user agent UI or platform state requires the [=XRSession/visibility state=] to be {{XRVisibilityState/"hidden"}} or {{XRVisibilityState/"visible-blurred"}}, set |session|'s [=XRSession/visibility state=] to {{XRVisibilityState/"visible"}}.
1. Abort these steps.
1. If the user agent can show a [=browser overlay=] over |session| while preserving the [=immersive session=], run the following steps:
1. Show a [=browser overlay=] over |session|.
1. Set |session|'s [=XRSession/browser overlay shown=] boolean to `true`.
1. If no other user agent UI or platform state requires the [=XRSession/visibility state=] to be {{XRVisibilityState/"hidden"}}, set |session|'s [=XRSession/visibility state=] to {{XRVisibilityState/"visible-blurred"}}.
1. Abort these steps.
1. Otherwise, [=Shut down the session|shut down=] |session|.

@alcooper91 alcooper91 Jun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WIthout a way to feature detect support this feels like a bit of a footgun. At minimum I think if we want this behavior we need to add a member boolean that can indicate support; but I wonder if returning a bool (that indicates if toggling was succesful) or a promise (bool is true for shown, false for hidden and rejected if overlay couldn't be toggled), would also be acceptable.

@cabanier cabanier Jul 2, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The developer will call this API if they want the user to enter some information on the 2D web page. I can't think of a scenario where they wouldn't want to exit WebXR if overlay is not supported.

@alcooper91 alcooper91 Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe they can work around it, or if they can summon their own keyboard maybe they can pipe the data through? If it's payment, maybe there's some improvements that could be made to the payments API, etc.

Requesting a feature leading to an exit without a way to validate just feels like a massive footgun to me; maybe the reason the page wanted the overlay was optional to begin with.

@cabanier cabanier Jul 6, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If they go through the trouble of building an alternate input systen, they will likely choose that as their only option.
If we do NOT exit, developers will just assume it worked since they only test on Quest which leaves a broken workflow on other platforms.

@alcooper91 alcooper91 Jul 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In thinking about it a bit more, I think I'm not opposed to failure meaning you end the session (since we have the event you should be listening for), but I do think we should have a way to feature detect. At the very least, maybe you want to switch to display a message and a button or a different message if you know the overlay won't work.


Note: If the user agent is unable to show a [=browser overlay=] over an [=immersive session=], calling {{XRSession/toggleOverlay()}} can end the session and return the user to the non-immersive browser interface.

</div>

<div class="algorithm" data-algorithm="initialize-session">

To <dfn>initialize the session</dfn>, given |session|, |mode|, |granted|, and |device|, the user agent MUST run the following steps:
Expand Down Expand Up @@ -2873,6 +2901,7 @@ Broadly speaking, there are two options for user agents who wish to support [=tr
<div class="note">
Note: Examples of [=trusted UI=] include:
- The default 2D mode browser shown when not in immersive mode
- A [=browser overlay=] shown in response to {{XRSession/toggleOverlay()}}
- A prompt shown within immersive mode which can only be interacted with via a reserved hardware button to prevent spoofing
- Pausing the immersive session and showing some form of native system environment in which a prompt can be shown

Expand Down Expand Up @@ -3112,6 +3141,7 @@ Changes from the <a href="https://www.w3.org/TR/2022/CR-webxr-20220331/">Candida
- Transient intent addition (<a href="https://github.com/immersive-web/webxr/pull/1343">GitHub #1343</a>)
- First draft for adding a property to XRInputSource to say it's visible elsewhere (<a href="https://github.com/immersive-web/webxr/pull/1353">GitHub #1353</a>)
- Clarify rgb vs srgb behavior (<a href="https://github.com/immersive-web/webxr/pull/1359">GitHub #1359</a>)
- Add XRSession.toggleOverlay()


<h3 id="changes-from-20200724" class="no-num">
Expand Down
Loading