How to use Fullscreen API.

Front-end developers add additional features to an application during development. Some of these features are not used as often as others, and can be simple, but a bit confusing.

Introducing Fullscreen API.

This browser API provides you with several methods and properties that you can use to enter, quit, or modify the fullscreen state.

In this article, we will explore how to utilize Fullscreen API by using the example of the fullscreen button.

Basics

First, we need to make sure it is possible to enter fullscreen on a page using the document.fullscreenEnabled property. It returns a boolean value indicating whether fullscreen is available.

console.log(document.fullscreenEnabled); // <· true or false

Then, to put our element into a fullscreen mode, we need to ensure there is no element in this mode already present within the document. To do this, we can check the document.fullscreenElement property. If it is null, then fullscreen is not currently in use, otherwise, it will return an element that is in fullscreen mode.

console.log(document.fullscreenElement); // <· null or Element

To enter fullscreen mode, we need to make a request to the element we want to set. We do not make the request to document or window, but directly to the Element, e.g., we want to show our page in fullscreen, then we need to make a request to document.documentElement. We can complete this by using Element.requestFullscreen method call. This method is asynchronous and returns a Promise. If permission is granted, this promise is resolved and the element receives a fullscreenchange event that is bubbling and can be caught on the document. If not, we can catch a fullscreenerror instead.

By default, the browser navigation UI will be hidden in fullscreen mode. However, it is possible to also keep the navigation UI in fullscreen mode by using the navigationUI parameter:

document.documentElement
    .requestFullscreen({
        navigationUI: "show"
    })
    .then(() => {
        console.log('Element entered fullscreen mode                                                 
                     successfully.');
    )
    .catch(error => {
         console.log(`Entering fullscreen mode failed:
                      ${error.message}`);
    });

Then, if we want to quit fullscreen mode, we simply need to call document.exitFullscreen method. It does not matter which element is in fullscreen:

document.exitFullscreen()
    .then(() => {
        console.log('Element has exited fullscreen mode 
                     successfully');
    })
    .catch(error => {
        console.log(`Something went wrong ${error.message}`);
    });

Now we can put it all together. Let’s say that we have a button that brings up our document in fullscreen mode.

HTML:

<div class="fullscreen-button">
    <div class="fullscreen-enter">
        enter fullscreen
    </div>
    <div class="fullscreen-exit">
        exit fullscreen
    </div>
</div>

JS:

const fullscreenButton = document.querySelector('.fullscreen-button');
fullscreenButton.addEventListener('click', () => {
    if (document.fullscreenElement === null) {
        document.documentElement
            .requestFullscreen()
            .catch(error => {
                console.log(`Entering fullscreen mode failed:   
                             ${error.message}`);
            });
    } else {
        document.exitFullscreen();
    }
});

Now we can set fullscreen on and off, but our button does not change. We can do this on requestFullscreen method call success, but we need it to change on Esc button press as well. We should catch fullscreenchange event on the document for this:

document.addEventListener('fullscreenchange', () => {
    if (document.fullscreenElement !== null) {
        fullscreenButton.classList.add('active')
    } else {
        fullscreenButton.classList.remove('active');
    }
});

You can play with this example here.

Using Fullscreen API with other elements

In addition to setting the whole page into fullscreen mode, we can also set other elements. For example, we can show iframe in this mode by calling requestFullscreen on it:

const iframeElement = document.querySelector('iframe');
iframeElement.requestFullscreen().then(() => {
    /* do something */
);

You can do the same with images, divs, anchors, and other elements if this not restricted by your browser.

Feature policy: iframe

MDN says:

By default, top-level documents and their same-origin child frames can request and enter fullscreen mode. This directive allows or prevents cross-origin frames from using fullscreen mode.

This means that, if we want to enter fullscreen from a page embedded as a cross-origin iframe, we can occur fullscreenerror. To allow fullscreen for this iframe, we need to add legacy but continue to work attribute allowfullscreen=”true” or modern one allow=”fullscreen;”.

Going fullscreen programmatically

Note that you cannot force your page to be displayed in fullscreen mode for security reasons. User interaction is required for that. If you do that you will get an error similar to the following:

It means that the only way to go fullscreen from our code is by handling user events such as click or keydown.

Styling

:fullscreen

When an element enters fullscreen mode, we can add specific CSS styles to it using this pseudo-class. This applies only to an element on which fullscreen was accepted.

<div class="fullscreen-element">
    <span>Text</span>
</div>
// this works - "Text" is red
.fullscreen-element:fullscreen {
    color: red;
}
// this doesn't work - "Text" is still red
// because span is not fullscreen element
.fullscreen-element span:fullscreen {
    color: blue;
}

::backdrop

A fullscreen element may have a default black background. We can change it by using this pseudo-element:

.fullscreen-element::backdrop {
    color: red;
}

F11 and Document Fullscreen

F11 fullscreen mode is a browser/OS feature that you do not have access to from javascript, just like you do not have access to the address bar display.

Also, these APIs are separate and not “connected” to each other, so you are able to enter fullscreen mode via API even if your browser is already presented in its own fullscreen via F11.

¯*(ツ)*/¯

Сross-browser compatibility

Not all new features are supported by every browser. Fullscreen API is no exception. Currently, only Firefox >64 and Chrome >71 support this unprefixed. To use it in different browsers without unnecessary headaches, we can use fscreen.

Conclusion

As we reviewed, Fullscreen API is a user-friendly browser feature, but has a few pitfalls that are useful to know.

If you have something to add, please let me know in the comments below.