Fullscreen Events

An overview of fullscreen events, it's utilization and how to catch any errors

Kong Her 2025-2-17

`fullscreenchange` and `fullscreenerror` Events

What are these Events?

The fullscreenchange and fullscreenerror events are part of the Fullscreen API in JavaScript. These events allow developers to monitor changes in fullscreen mode and handle potential errors.

fullscreenchange: This event triggers whenever the document enters or exits fullscreen mode, enabling developers to adjust UI elements accordingly.
fullscreenerror: This event triggers when an error occurs while attempting to enter or exit fullscreen mode. This helps detect issues, such as when a browser restricts fullscreen access due to security policies.

Why Would I Use These Events?

Enhance user experience by modifying the UI in fullscreen mode.
Detect and handle fullscreen errors gracefully when fullscreen mode is unsupported.
Improve usability in media applications that rely on fullscreen mode.

Research Sources

Here are some useful resources for understanding these events:

Code Examples

Basic `fullscreenchange` Event Listener

The following example toggles fullscreen mode and updates the UI when fullscreen mode changes.

<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Fullscreenchange Example</title>
</head>
<body>
    <!-- Button to toggle fullscreen mode -->
    <button id="toggleFullscreen">Toggle Fullscreen</button>
    <!-- Displays fullscreen status -->
    <p id="status">Fullscreen status: Not active</p>

    <script>
        // Get references to the button and status text
        const button = document.getElementById('toggleFullscreen');
        const status = document.getElementById('status');

        // Add event listener to button click
        button.addEventListener('click', () => {
            // Check if the document is in fullscreen mode
            if (!document.fullscreenElement) {
                // Request fullscreen mode
                document.documentElement.requestFullscreen();
            } else {
                // Exit fullscreen mode
                document.exitFullscreen();
            }
        });

        // Listen for fullscreen mode changes
        document.addEventListener('fullscreenchange', () => {
            // Update the status text based on fullscreen mode state
            status.textContent = `Fullscreen status: ${document.fullscreenElement ? 'Active' : 'Not active'}`;
        });
    </script>
</body>
</html>

Handling `fullscreenerror` Events

This example demonstrates handling errors when attempting to enter fullscreen mode. It also includes an error message output to indicate why fullscreen mode failed.

<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Fullscreenerror Example</title>
</head>
<body>
    <!-- Button to attempt entering fullscreen mode -->
    <button id="enterFullscreen">Enter Fullscreen</button>
    <!-- Placeholder for error messages -->
    <p id="errorMessage" style="color: red;"></p>

    <script>
        // Get references to the button and error message paragraph
        const button = document.getElementById('enterFullscreen');
        const errorMessage = document.getElementById('errorMessage');

        // Add event listener to button click
        button.addEventListener('click', () => {
            // Try entering fullscreen mode
            document.documentElement.requestFullscreen().catch(err => {
                // Log error to console and display error message
                console.error(err);
                errorMessage.textContent = 'Error: Unable to enter fullscreen. The request may be blocked by browser settings or permissions.';
            });
        });

        // Listen for fullscreen error events
        document.addEventListener('fullscreenerror', () => {
            // Display an error message if fullscreen fails
            errorMessage.textContent = 'Error: An issue occurred while attempting to enter fullscreen mode.';
        });
    </script>
</body>
</html>

Example of a Fullscreen Error

To give some examples of how an error could occur, here’s some scenarios:

A browser may block fullscreen mode if the request is not triggered by a user gesture (e.g., clicking a button).
Some devices or browser settings restrict fullscreen mode to specific domains or require explicit user permissions.
Trying to enter fullscreen mode on an iframe from a different domain without the correct permissions may trigger a fullscreenerror.

Example Error Output in Console

If fullscreen mode fails, the following error message may appear in the browser’s developer console:

Uncaught (in promise) TypeError: fullscreen request was denied because it was not triggered by user activation.

To prevent this error, ensure the request is made inside an event handler (e.g., inside a click event listener).

Conclusion

fullscreenchange is useful for updating the UI when fullscreen mode changes.
fullscreenerror is essential for handling and debugging fullscreen failures.
Understanding common fullscreen issues can help prevent errors and improve user experience.

By implementing these best practices, developers (that's us) can create more seamless fullscreen experiences while minimizing potential issues.