JavaScript Fullscreen API

Introducción a la JavaScript Fullscreen API

La JavaScript Fullscreen API permite que una página web solicite al navegador mostrar un único elemento — y solo ese elemento — ocupando toda la pantalla, ocultando la barra de direcciones, las pestañas y el chrome del sistema operativo. Esto es lo que impulsa el botón de pantalla completa que ves en los reproductores de video, juegos en línea, herramientas de presentación y galerías de imágenes.

Este capítulo cubre cómo entrar y salir del modo de pantalla completa, cómo reaccionar a los cambios con eventos, los errores comunes que encontrarás (el requisito del gesto del usuario, la Promise que devuelve y el estilo), y el soporte de navegadores. Los métodos y propiedades clave son:

• Element.requestFullscreen() — solicita que un elemento ocupe toda la pantalla. Devuelve una Promise.
• Document.exitFullscreen() — sale de pantalla completa y vuelve a la página normal.
• document.fullscreenElement — el elemento que se muestra actualmente en pantalla completa, o null si no hay ninguno.
• document.fullscreenEnabled — true si la pantalla completa está disponible y no está bloqueada.
• Eventos fullscreenchange / fullscreenerror — se disparan cuando cambia el estado o falla una solicitud.

Activar el modo de pantalla completa en JavaScript

Para entrar en pantalla completa, llama al método requestFullscreen() sobre cualquier elemento del DOM que quieras ampliar — un video, un <div>, un <canvas>, o incluso todo el document.documentElement.

Hay dos reglas importantes desde el principio:

1. Se requiere un gesto del usuario. Los navegadores solo respetan requestFullscreen() cuando se ejecuta dentro de una interacción real, como un clic o una pulsación de tecla. Llamarlo al cargar la página o desde un temporizador se rechaza silenciosamente, por lo que casi siempre se llama desde dentro de un manejador de eventos.
2. Devuelve una Promise. La Promise se resuelve cuando el modo de pantalla completa se activa correctamente y se rechaza (con un error) si el navegador lo deniega. Añade siempre un .catch() para que un rechazo no se convierta en un rechazo no gestionado.

<div id="main-content">
    <button id="fs-btn">Go Fullscreen</button>
    <div id="video-container">
        <!-- Your content like a video or interactive media -->
    </div>
</div>

<script>
const element = document.getElementById("video-container");
const btn = document.getElementById("fs-btn");

btn.addEventListener("click", function() {
    if (document.fullscreenEnabled) {
        element.requestFullscreen().catch(err => {
            console.error(`Error attempting to enable fullscreen: ${err.message}`);
        });
    } else {
        console.log("Fullscreen API is not supported in this browser.");
    }
});
</script>

Este fragmento activa la pantalla completa para el elemento video-container cuando se hace clic en el botón. La comprobación de document.fullscreenEnabled protege contra navegadores (o contextos embebidos como un <iframe> en modo sandbox) donde la función no está disponible, y el .catch() reporta cualquier rechazo en lugar de dejar que falle silenciosamente.

Controlar la interfaz de navegación

requestFullscreen() acepta un objeto de opciones opcional. La propiedad navigationUI indica al navegador si debe mantener visibles sus controles de navegación (botón de atrás, barra de URL):

// "hide"  → request a truly immersive, chrome-free view (default for most browsers)
// "show"  → keep the browser's navigation UI on screen
// "auto"  → let the browser decide
element.requestFullscreen({ navigationUI: "hide" });

Solo es una sugerencia — el navegador puede ignorarla — pero es útil para juegos y video donde se desea la experiencia más inmersiva posible.

Salir del modo de pantalla completa

Una página solo puede tener un elemento en pantalla completa a la vez, por lo que no necesitas saber qué elemento está activo para salir — document.exitFullscreen() siempre sale del actual y devuelve la página a su diseño normal:

<div id="exit-button">
    <button id="exit-btn">Exit Fullscreen</button>
</div>

<script>
document.getElementById("exit-btn").addEventListener("click", function() {
    if (document.exitFullscreen) {
        document.exitFullscreen();
    }
});
</script>

Aquí el usuario sale de la pantalla completa haciendo clic en el botón Exit Fullscreen. La comprobación if (document.exitFullscreen) confirma que el método existe antes de llamarlo. Ten en cuenta que el navegador también permite al usuario salir en cualquier momento pulsando Esc — tu código no controla eso, que es exactamente por qué deberías escuchar el evento fullscreenchange en lugar de asumir que tu botón es la única salida.

Gestionar los cambios de pantalla completa con eventos

La Fullscreen API dispara eventos cada vez que cambia el estado, sin importar cómo ocurrió — tu botón, la tecla Esc o el propio navegador. Escucharlos es la forma confiable de mantener tu interfaz sincronizada (por ejemplo, intercambiar un icono de "entrar" por uno de "salir"):

document.addEventListener("fullscreenchange", function(event) {
    if (document.fullscreenElement) {
        console.log("Entered fullscreen mode");
    } else {
        console.log("Exited fullscreen mode");
    }
});

Este escuchador de eventos registra mensajes en la consola según si el documento está en modo de pantalla completa o no, lo que ayuda a los desarrolladores a entender las transiciones de estado. Además, debes gestionar el evento fullscreenerror para capturar los casos en que el navegador deniega la solicitud (por ejemplo, debido a restricciones de seguridad o cancelación del usuario):

document.addEventListener("fullscreenerror", function(event) {
    console.error("Fullscreen request failed:", event.target.error);
});

Aquí event.target es el elemento sobre el que se realizó la solicitud; leer .error en él (o simplemente registrar el evento) te indica por qué el navegador lo rechazó.

Ahora juntemos todo en un ejemplo completo y funcional:

Un ejemplo completo

<div id="main-content">
    <button id="fs-btn">Go Fullscreen</button>
    <div id="video-container" style="position: relative; height: 100vh; display: flex; align-items: center; justify-content: center;">
        <div id="exit-button" style="display: none;">
            <button id="exit-btn">Exit Fullscreen</button>
        </div>
    </div>
</div>

<script>
const element = document.getElementById("video-container");
const exitBtn = document.getElementById("exit-btn");
const exitButtonContainer = document.getElementById("exit-button");

document.getElementById("fs-btn").addEventListener("click", function() {
    if (document.fullscreenEnabled) {
        element.requestFullscreen().catch(err => {
            console.error(`Error attempting to enable fullscreen: ${err.message}`);
        });
    }
});

exitBtn.addEventListener("click", function() {
    if (document.exitFullscreen) {
        document.exitFullscreen();
    }
});

function updateButtonVisibility() {
    exitButtonContainer.style.display = document.fullscreenElement ? "block" : "none";
}

document.addEventListener("fullscreenchange", updateButtonVisibility);
document.addEventListener("fullscreenerror", function(event) {
    console.error("Fullscreen request failed:", event.target.error);
});
</script>

Así funciona cada parte:

• El manejador de "Go Fullscreen" comprueba document.fullscreenEnabled y luego llama a element.requestFullscreen() sobre el contenedor de video, capturando cualquier rechazo.
• El manejador de "Exit Fullscreen" llama a document.exitFullscreen() para volver a la página normal.
• updateButtonVisibility() muestra el botón de salida solo cuando hay un elemento realmente en pantalla completa, leyendo document.fullscreenElement.
• El escuchador de fullscreenchange ejecuta updateButtonVisibility() en cada cambio de estado — incluyendo cuando el usuario pulsa Esc — para que la interfaz nunca quede desincronizada, y el escuchador de fullscreenerror reporta una solicitud denegada.

Compatibilidad y soporte de navegadores

La Fullscreen API es compatible con todos los navegadores modernos — Chrome, Firefox, Safari, Opera y Edge — usando los métodos estándar sin prefijo. Las versiones antiguas de Safari (y versiones muy antiguas de Chrome/Edge) usaban el prefijo -webkit- (webkitRequestFullscreen, webkitExitFullscreen). Si necesitas dar soporte a estos, recurre al nombre con prefijo:

function openFullscreen(element) {
    if (element.requestFullscreen) {
        return element.requestFullscreen();
    }
    if (element.webkitRequestFullscreen) { // older Safari
        return element.webkitRequestFullscreen();
    }
}

function closeFullscreen() {
    if (document.exitFullscreen) {
        return document.exitFullscreen();
    }
    if (document.webkitExitFullscreen) { // older Safari
        return document.webkitExitFullscreen();
    }
}

Para dar estilo a un elemento mientras está en pantalla completa, usa la pseudoclase CSS :fullscreen:

#video-container:fullscreen {
    background-color: #000;
    color: #fff;
    padding: 20px;
}

Errores comunes

• Sin gesto del usuario, sin pantalla completa. Llamar a requestFullscreen() fuera de un manejador de clic o de tecla es rechazado. Actívalo desde una interacción real.
• Los iframes en modo sandbox están bloqueados a menos que el iframe tenga el atributo allow="fullscreen".
• Gestiona el rechazo de la Promise. Un usuario puede denegar la solicitud, o la política puede bloquearla — añade siempre .catch().
• No confíes solo en tu propio botón. La tecla Esc sale de la pantalla completa sin tocar tu código, así que usa el evento fullscreenchange para actualizar la interfaz.

Conclusión

La Fullscreen API te ofrece una forma limpia y basada en gestos de permitir que un único elemento ocupe la pantalla para video, juegos, presentaciones y galerías. Recuerda lo esencial: solicita desde un gesto del usuario, gestiona la Promise devuelta, sal con document.exitFullscreen() y mantén tu interfaz sincronizada escuchando el evento fullscreenchange en lugar de asumir cómo el usuario salió de la pantalla completa.

Para seguir aprendiendo, explora los eventos del navegador, la manipulación del DOM y las Promises, en los que se basa la Fullscreen API.

Práctica