A Work in Progress

developer's blog by Wei
lots of work in progress notes
TimelineCredits

Request Fullscreen

October 26, 2019

Slides should be played full screen when prensenting. When you maximize window with Chrome, it hides the URL and bookmark bars for you. But if you use FireFox, you cannot hide them unless you request fullscreen.

Note: the context of this note is building the slides features on my site.

Understanding the API

The fullscreen APIs are a set of web APIs implemented by browsers that allow us to request fullscreen on an element, triggered by a user event.

You can read more from the MDN docs on the Fullscreen API. They have a great usage guide as well. The example code it provides is straightforward enough for you to start tweaking:

function toggleFullScreen() {
  if (!document.fullscreenElement) {
    document.documentElement.requestFullscreen();
  } else {
    if (document.exitFullscreen) {
      document.exitFullscreen();
    }
  }
}

I have a few takeaways:

requestFullScreen is requested by and acts on the element

At first it did not appear apparent to me that the full screen requests are raised by elements and not the document. However, this gives us fine control over which element goes full screen.

Once the element goes full screen, it gets the size of your screen. If its content is longer than a full screen, it can scroll like in normal overflow. I think this is how YouTube implements its behavior whereby once you go full screen, you will watch the video play in full screen, but you can scroll down to browse the remaining content of the original page. The layout is similar with the theater mode.

You can check out my naïve implementation in this CodeSandbox that demonstrates the behaviors said above.

The request can only be called from inside a user-generated event

Can you create a UI where user enters your page and boom, it goes full screen?

No. Because,

requestFullscreen() can only be called from inside a short running user-generated event handler

A few quick searches indicate that a lot of people are running into problems with this, including this recent issue from Microsoft/VSCode Web: cannot go fullscreen or copy via Quick Open from Firefox #83288.

The MDN web docs has a small note explaining this:

Note: Fullscreen requests need to be called from within an event handler or otherwise they will be denied.

It has some further explanation on what happens when the request fails as well, in the Element.requestFullScreen() API doc.

If not for this exploration, I did not know that there is a living HTML Specification and according to which the legit activation events for the fullscreen API (and a few others) are:

  • change
  • click
  • contextmenu
  • dblclick
  • mouseup
  • pointerup
  • reset
  • submit
  • touchend

In addition, the fullscreen request can also be triggered by a user-generated orientation change.

If you wonder how to get rejected by the fullscreen API, I initially implemented the trigger in a React.useEffect handler that watches location change - since it picks up mode change from URL. But it would fail since it is not in one of the native user generated events.

Another limitation I later on encountered is that I cannot then put this request in my ownself implemented Gamepad API triggerer for the same reason.

You can try commenting out the relevant code in this CodeSandbox and see the error for yourself.

Other APIs that can only be called inside such "short running user-generated event handler", or, "short-lived event handler" include the Clipboard APIs (but you can request permission for this one).

Links