How to use web Fullscreen API

Have you ever wondered how the fullscreen button on web video players works? The answer to that is quite simple, they leverage the browser's Fullscreen API.

The Fullscreen API augments the Document and Element interfaces with a few methods, properties, and event handlers to allow turning on or off the fullscreen mode for a specific Element.

TLDR;
Document.fullscreenEnabled - tells you if fullscreen mode is available
Element.requestFullscreen() - engage fullscreen mode for an element
Document.exitFullscreen() - switch back to windowed mode
Document.fullscreenElement - returns the element which is currently fullscreen or null
fullscreenchange - event emitted by an element when it switches to fullscreen or back
fullscreenerror - event emitted by an element when it errors while engaging fullscreen
:fullscreen - CSS pseudo-class that targets the fullscreen element

Since the API is not that vast let's go straight to how to use it.

Before calling any method is recommended to first check if the functionality is available, you do that by accessing document.fullscreenEnabled boolean property which indicates whether the fullscreen mode is available.

if (document.fullscreenEnabled) {
    console.log("Your browser can use fullscreen right now");
    ...
} else {
    console.log("Your browser cannot use fullscreen right now");
    ...
}

Knowing that the functionality is available next step would be to engage it. Engaging is done by calling requestFullscreen on the Element you want to become fullscreen.

let element = document.querySelector("videoPlayer");

element.requestFullscreen()
    .then(() => console.log("Fullscreen engaged successfully"))
    .catch(err => console.log(`Error engaging fullscreen ${err.message}`));

requestFullscreen returns a Promise which on completion resolves with undefined and on error it rejects the promise with the specific error.
It is worth noting that only elements that meet the following requirements can engage fullscreen mode:

It's not a dialog element
It must be located in the top-level document, or inside an iframe with the allowfullscreen attribute.

To exit, the user can press the F11 or Esc keys, to exit programmatically call the exitFullscreen method of Document.

if (document.fullscreenElement) {
  document
    .exitFullscreen()
    .then(() => console.log("Exited from fullscreen mode"))
    .catch((err) => console.error(err));
}

Same as requestFullscreen the exitFullscreen method returns a Promise which resolves with undefined and on error it rejects with the specific error.
Notice the use of fullscreenElement property in the example above, this property contains the Element that is currently in fullscreen or null if none is.

For more flexibility, there are two noncancellable events emitted by the targeted Element:

fullscreenchange - emitted by an Element immediately after it switches into or out of fullscreen.
fullscreenerror - emitted by an Element when the browser for whatever reason fails to enter fullscreen mode.

To help with styling, the :fullscreen pseudo-class matches the element that is currently in fullscreen allowing you to adjust the layout when the element switches to fullscreen and back.

How to use Fullscreen API