toggleOverlay proposal by cabanier · Pull Request #1439 · immersive-web/webxr

cabanier · 2026-06-29T18:16:47Z

alcooper91 · 2026-06-30T20:09:24Z

+    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|.


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.

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.

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.

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.

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.

Add a note that browser overlays can display cross-origin content, unlike the HTML-in-Canvas API. Require XRSession.toggleOverlay() to be invoked with transient activation and throw SecurityError otherwise.

cabanier · 2026-07-06T15:48:27Z

/agenda toggleOverlay proposal

alcooper91 · 2026-07-07T21:08:27Z

+
+  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.


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

Is that listed somewhere else in this algorithm?

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

alcooper91 · 2026-07-07T21:11:24Z

This seems reasonable to me with these changes as we discussed (and a couple of minor nitpicks). I'd like to allow the others to weigh in though.

mwyrzykowski

What are the use cases for this? Payments are mentioned, but all major browsers already support the payments API which seems preferable to opening a browser window. E.g., some UAs may open native system UI for payments instead of the entire browser.

It would be good to understand what the goals are here and if they are already achievable via existing web APIs. Opening a browser window seems like it does not exactly fit with the rest of the WebXR API.

cabanier · 2026-07-11T03:10:47Z

What are the use cases for this? Payments are mentioned, but all major browsers already support the payments API which seems preferable to opening a browser window. E.g., some UAs may open native system UI for payments instead of the entire browser.

FWIW Quest browser does not support payments. Is there any browser that supports payments inside of a WebXR session?

It would be good to understand what the goals are here and if they are already achievable via existing web APIs. Opening a browser window seems like it does not exactly fit with the rest of the WebXR API.

The goal is to have a 2d page that can potentially open another tab or display third party content.

mwyrzykowski · 2026-07-11T18:42:19Z

FWIW Quest browser does not support payments. Is there any browser that supports payments inside of a WebXR session?

I don't think so but support couldn't be added if that was needed.

The goal is to have a 2d page that can potentially open another tab or display third party content.

Specifically Apple is wondering, what content would be displayed that is relevant to an immersive session? It seems a bit out of place with the rest the WebXR API to be showing browser windows. We are wondering if all content desired could be displayed via existing web APIs?

cabanier · 2026-07-13T15:28:59Z

FWIW Quest browser does not support payments. Is there any browser that supports payments inside of a WebXR session?

I don't think so but support couldn't be added if that was needed.

It's very hard to do so which is why it hasn't happened yet. It unclear if users can trust UI that is displayed inside an immersive session.

The goal is to have a 2d page that can potentially open another tab or display third party content.

Specifically Apple is wondering, what content would be displayed that is relevant to an immersive session? It seems a bit out of place with the rest the WebXR API to be showing browser windows. We are wondering if all content desired could be displayed via existing web APIs?

It's mostly convenience + the ability to show third party content

payments
upsells (ie the webxr site is a demo of a native app)
tutorials
game lobby

alcooper91 · 2026-07-13T16:13:54Z

It's mostly convenience + the ability to show third party content

payments
upsells (ie the webxr site is a demo of a native app)
tutorials
game lobby

TBH, I think HTML in canvas could likely handle the last 2 and maybe even the last 3. Though I guess cross-origin libraries would be banned?

cabanier · 2026-07-13T16:20:22Z

It's mostly convenience + the ability to show third party content

payments
upsells (ie the webxr site is a demo of a native app)
tutorials
game lobby

TBH, I think HTML in canvas could likely handle the last 2 and maybe even the last 3. Though I guess cross-origin libraries would be banned?

Sure, it could do those things in VR but it's a lot easier to just do it in 2D especially if your site also supports a 2d experience.

alcooper91 · 2026-07-13T16:24:37Z

If you just smack a canvas on a quad texture can you not basically create a 2D page with HTML-in-Canvas? It's just restricted to your origin?

cabanier · 2026-07-13T18:04:13Z

If you just smack a canvas on a quad texture can you not basically create a 2D page with HTML-in-Canvas? It's just restricted to your origin?

Not right now because we have not defined hit testing with html-in-canvas

alcooper91 · 2026-07-13T20:47:42Z

  undefined updateRenderState(optional XRRenderStateInit state = {});
  Promise&lt;undefined&gt; updateTargetFrameRate(float rate);
  [NewObject] Promise&lt;XRReferenceSpace&gt; requestReferenceSpace(XRReferenceSpaceType type);
+  undefined toggleOverlay();


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.

mwyrzykowski · 2026-07-13T21:15:44Z

It's mostly convenience + the ability to show third party content

payments
upsells (ie the webxr site is a demo of a native app)
tutorials
game lobby

TBH, I think HTML in canvas could likely handle the last 2 and maybe even the last 3. Though I guess cross-origin libraries would be banned?

And payments is possible with existing web APIs, UAs would just need to support it. It would be their choice to exit the immersive session or remain within it.

It doesn't seem like there is a compelling use case to justify adding this to the WebXR specification at this time

cabanier · 2026-07-13T21:23:29Z

It's mostly convenience + the ability to show third party content

payments
upsells (ie the webxr site is a demo of a native app)
tutorials
game lobby

TBH, I think HTML in canvas could likely handle the last 2 and maybe even the last 3. Though I guess cross-origin libraries would be banned?

And payments is possible with existing web APIs, UAs would just need to support it. It would be their choice to exit the immersive session or remain within it.

Not all sites want or can use the web payments API.
Today, they lose a lot of business from the friction of exiting WebXR and then having to re-enter. This API would get rid of this friction by either blurring or suspending/resuming the session

It doesn't seem like there is a compelling use case to justify adding this to the WebXR specification at this time

I don't quite follow. This is something developers have asked for. Why would we not let them use the browser if it's available? It seems anti-web that we force them to do everything in script.

alcooper91 · 2026-07-13T21:40:30Z

Not right now because we have not defined hit testing with html-in-canvas

To me that's more an argument for us working to try to solve that than implement this, but l do agree that payments is the big workflow that this enables that html-in-canvas doesn't, and maybe there's others. There's also the simplicity argument.

I think @mwyrzykowski was implying that the UA could override the payments implementation if there's a WebXR session to create a way to show it within the WebXR session if they so desired, which achieves your goal.

mwyrzykowski · 2026-07-13T21:53:29Z

I think @mwyrzykowski was implying that the UA could override the payments implementation if there's a WebXR session to create a way to show it within the WebXR session if they so desired, which achieves your goal.

Exactly. There doesn't seem to be any reason to add API surface to WebXR here.

cabanier · 2026-07-13T21:56:00Z

I think @mwyrzykowski was implying that the UA could override the payments implementation if there's a WebXR session to create a way to show it within the WebXR session if they so desired, which achieves your goal.

Exactly. There doesn't seem to be any reason to add API surface to WebXR here.

I disagree that there is no reason at all to add this.

mwyrzykowski · 2026-07-13T22:07:40Z

@cabanier Apple discussed a bit would like to understand the use cases as the justification for adding this is not obvious.

For instance, why can't the sites use the payments API?

Are there other use cases which are not possible with existing web APIs and, if so, which ones?

alcooper91 · 2026-07-13T22:22:00Z

FWIW, I think this may be better discussed in a meeting at this point?

/agenda

toggleOverlay proposal

97a3fa7

cabanier requested review from AdaRoseCannon, alcooper91 and toji June 29, 2026 18:17

cabanier mentioned this pull request Jun 29, 2026

Give developers control over "overlay" browser #1365

Open

alcooper91 reviewed Jun 30, 2026

View reviewed changes

Comment thread index.bs

Clarify browser overlay toggle requirements

aafde89

Add a note that browser overlays can display cross-origin content, unlike the HTML-in-Canvas API. Require XRSession.toggleOverlay() to be invoked with transient activation and throw SecurityError otherwise.

probot-label Bot added the agenda Request discussion in the next telecon/FTF label Jul 6, 2026

Yonet removed the agenda Request discussion in the next telecon/FTF label Jul 6, 2026

address comments from 7/7/2026 meeting

d4dba6a

cabanier requested a review from alcooper91 July 7, 2026 20:56

alcooper91 reviewed Jul 7, 2026

View reviewed changes

Comment thread index.bs Outdated

adddress review comment

708a0cd

mwyrzykowski reviewed Jul 10, 2026

View reviewed changes

alcooper91 reviewed Jul 13, 2026

View reviewed changes

probot-label Bot added the agenda Request discussion in the next telecon/FTF label Jul 13, 2026

Uh oh!

Conversation

cabanier commented Jun 29, 2026 • edited by pr-preview Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cabanier commented Jul 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alcooper91 commented Jul 7, 2026

Uh oh!

mwyrzykowski left a comment

Choose a reason for hiding this comment

Uh oh!

cabanier commented Jul 11, 2026

Uh oh!

mwyrzykowski commented Jul 11, 2026

Uh oh!

cabanier commented Jul 13, 2026

Uh oh!

alcooper91 commented Jul 13, 2026

Uh oh!

cabanier commented Jul 13, 2026

Uh oh!

alcooper91 commented Jul 13, 2026

Uh oh!

cabanier commented Jul 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mwyrzykowski commented Jul 13, 2026

Uh oh!

cabanier commented Jul 13, 2026

Uh oh!

alcooper91 commented Jul 13, 2026

Uh oh!

mwyrzykowski commented Jul 13, 2026

Uh oh!

cabanier commented Jul 13, 2026

Uh oh!

mwyrzykowski commented Jul 13, 2026

Uh oh!

alcooper91 commented Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cabanier commented Jun 29, 2026 •

edited by pr-preview Bot

Loading