La API de FullSreen en JavaScript

Ver ejemplo Descargar

La API de FullScreen permite presentar una página web o los distintos elementos que forman la misma en pantalla completa o FullScreen, una vez que se encuentra el navegador en este modo, el navegador informa y brinda distintas opciones para salir de este modalidad.

La Fullscreen API permite mostrar un elemento HTML —o el documento completo— en pantalla completa. Su objetivo es simples: eliminar las distracciones de la interfaz, barras del navegador y otros elementos visuales para destacar un contenido específico (imagen, video, canvas, app, visor, etc.).

En proyectos multimedia y educativos suele ser indispensable. En mi caso, la usé por primera vez para destacar imágenes grandes y descubrí lo cómodo que es ofrecerle al usuario una experiencia inmersiva sin depender de plugins.

Qué es la Fullscreen API y para qué sirve

La Fullscreen API permite mostrar un elemento HTML -o el documento completo- en pantalla completa. Su objetivo es simples: eliminar las distracciones de la interfaz, barras del navegador y otros elementos visuales para destacar un contenido específico (imagen, video, canvas, app, visor, etc.).

En proyectos multimedia y educativos suele ser indispensable; yo la usé por primera vez para destacar imágenes grandes y descubrí lo cómodo que es ofrecerle al usuario una experiencia inmersiva sin depender de plugins.

Cómo funciona el modo pantalla completa en navegadores modernos

El modo fullscreen actual requiere tres pilares:

• Llamada explícita a element.requestFullscreen()
• Una interacción del usuario previa (clic, touch, keypress)
• Permisos internos del navegador

El navegador crea un “contexto fullscreen” temporal donde el elemento seleccionado es el único protagonista. Este modo se destruye cuando el usuario presiona Esc, hace un gesto de salir o llamas desde código a document.exitFullscreen().

Requisitos y gestos del usuario para activar fullscreen

La API no puede invocarse sola. Los navegadores modernos bloquean cualquier petición sin gesto del usuario porque se considera una acción poderosa: elimina UI, maximiza pantalla y cambia el contexto visual.

Esto explica por qué, cuando estaba empezando, requestFullscreen() me fallaba sin razón aparente. La causa: lo ejecutaba dentro de un callback que no era “interacción directa”. Desde entonces lo disparo únicamente desde botones, links o eventos táctiles.

Cómo activar pantalla completa con JavaScript (requestFullscreen)

element.requestFullscreen() es el corazón de la API. Permite que cualquier elemento entre en pantalla completa: un <div>, un <video>, un <img> o incluso un canvas.

const imagen = document.getElementById("foto");
imagen.requestFullscreen();

Esta simple llamada activa el modo fullscreen siempre que el navegador lo permita y que exista un gesto del usuario.

Cuando probé esto por primera vez con imágenes grandes, noté lo útil que es para captar la atención del usuario. El contraste entre la interfaz completa y el modo inmersivo es enorme.

Cómo activar pantalla completa con JavaScript (requestFullscreen)

document.fullscreenEnabled

Antes de emplear esta API es aconsejable verificar si el navegador permite el modo de pantalla completa y también se puede emplear para verificar el soporte de la API en el navegador:

• true: Si el navegador permite el modo de pantalla completa.
• false: Caso contrario.

if (document.fullscreenEnabled) {
 // resto del codigo
}

Entrar en el modo FullScreen: element.requestFullscreen()

Este método permite que un solo elemento obtenga la pantalla completa; por ejemplo la imagen presentada a continuación:

Resulta muy útil para cuando se desee resaltar elementos específicos; la sintaxis sería la siguiente:

var element = document.getElementById("image").requestFullscreen();

element.requestFullscreen() es el corazón de la API. Permite que cualquier elemento entre en pantalla completa: un <div>, un <video>, un <img> o incluso un canvas:

const imagen = document.getElementById("foto");
imagen.requestFullscreen();

Ejemplo simple con un elemento HTML

En este ejemplo, puedes ver un HTML y el Script para al darle un click ver la imagen el fullScreen:

<img id="tigre" src="tigre.png" alt="Tigre">
<script>
 document.getElementById("tigre").addEventListener("click", () => {
   document.getElementById("tigre").requestFullscreen();
 });
</script>

Problemas comunes al llamar requestFullscreen

Navegador sin soporte → Solución: comprobar

if (!document.fullscreenEnabled) { /* fallback */ }

• Llamada sin interacción del usuario (muy frecuente).
• Llamada dentro de un iframe sin permisos adecuados el iframe necesitaba allow="fullscreen".
• Bloqueo por modo de navegación privada en algunos navegadores móviles.

Cómo salir del modo FullScreen (exitFullscreen): document.exitFullscreen()

Siendo el antagónico del método element.requestFullscreen(), este método cancela el modo FullScreen del navegador:

var element = document.getElementById("image");
element.exitFullscreen();

document.fullscreenElement()

Este otro método retorna todos los elementos del documento que actualmente está en modo pantalla completa (NULL en caso de no haber ningún elemento en este modo):

var element = document.getElementById("image");
element.fullscreenElement();

Un ejemplo de lo que podría retornar en caso de estar en modo pantalla completa:

<img id="img" src="tigre.png">

Eventos de FullScreen: fullscreenchange y fullscreenerror

Los eventos hacen la API realmente útil, sobre todo en interfaces dinámicas.

Cómo escuchar cuando un usuario entra o sale del modo pantalla completa

document.addEventListener("fullscreenchange", () => {
 if (document.fullscreenElement) {
   console.log("Entraste a fullscreen");
 } else {
   console.log("Saliste de fullscreen");
 }
});

Eventos de la API de FullScreen

document.fullscreenchange

Este evento se ejecuta cada vez que se entra y/o sale del modo pantalla completa o FullScreen; su sintaxis es la siguiente:

document.addEventListener("fullscreenchange", function() { 
 // resto del codigo
});

document.fullscreenerror

El modo FullScreen puede fallar; por ejemplo cuando se intenta otorgar el modo de pantalla completa desde un iframe.

Detectar qué elemento está en pantalla completa (fullscreenElement)

Este método resulta especialmente útil cuando quieres manipular el elemento activo. Yo lo uso mucho cuando tengo múltiples imágenes o videos y quiero saber cuál está ocupando la pantalla:

const activo = document.fullscreenElement;
console.log(activo);

Buenas prácticas para manejar la salida de fullscreen

• Asegura accesibilidad: ofrece un botón claro de “Salir”.
• Prevé que el usuario puede salir manualmente con Esc.
• Escucha siempre el evento fullscreenchange.
• Evita forzar al usuario a entrar repetidamente: algunos navegadores pueden bloquearte.

Errores habituales: iframes, permisos y restricciones

El evento fullscreenerror se dispara cuando algo falla:

document.addEventListener("fullscreenerror", () => {
 console.error("No se pudo activar fullscreen");
});

La causa más común: intentar entrar en fullscreen desde un iframe sin permisos. Yo me encontré con este problema varias veces hasta que entendí que el iframe debía incluir:

<iframe src="..." allow="fullscreen"></iframe>

Estilos y comportamiento visual en modo pantalla completa

La pseudoclase :fullscreen permite definir estilos exclusivos mientras un elemento está a pantalla completa.

Usar la pseudoclase CSS :fullscreen

img:fullscreen {
 object-fit: contain;
 background: #000;
}

Esto me gusta aplicarlo cuando quiero que una imagen se centre correctamente sin estirarse.

Adaptación en imágenes, videos y componentes interactivos

• Las imágenes pueden aplicar zoom adaptable.
• Los videos pueden ocultar controles innecesarios.
• Los canvas pueden redimensionarse dinámicamente.
• Si tu interfaz depende mucho de tamaño relativo, escucha también resize.

Compatibilidad por navegador y prefijos modernos

Soporte actual de Chrome, Firefox, Edge y Safari

Hoy prácticamente todos los navegadores modernos soportan la API sin prefijos.

Excepto Safari, que todavía puede requerir prefijos en versiones persistentes del ecosistema Apple.

¿Siguen siendo necesarios webkitRequestFullscreen y similares?

Ya no, pero si necesitas compatibilidad histórica o soportar software embebido antiguo, puedes incluirlas:

element.webkitRequestFullscreen?.();
element.msRequestFullscreen?.();

Yo usé estos prefijos hace años cuando trabajaba con navegadores muy antiguos; hoy casi nunca los necesito.

Ejemplo completo: activar y salir de fullscreen paso a paso

En este ejemplo, tenemos un par de botones para entrar y salir del modo pantalla completa:

<img id="img" src="tigre.png">
<button id="enter">Pantalla completa</button>
<button id="exit">Salir</button>
<script>
const img = document.getElementById("img");
document.getElementById("enter").onclick = () => {
 if (document.fullscreenEnabled) img.requestFullscreen();
};
document.getElementById("exit").onclick = () => {
 document.exitFullscreen();
};
document.addEventListener("fullscreenchange", () => {
 console.log(document.fullscreenElement
   ? "Modo fullscreen activo"
   : "Has salido de fullscreen");
});
</script>

Preguntas frecuentes sobre la API FullScreen en JavaScript

• ¿Puedo poner un div en pantalla completa?
  • Sí, cualquier elemento funciona.
• ¿Por qué no funciona requestFullscreen()?
  • Casi siempre por falta de gesto del usuario o permisos.
• ¿Puedo detectar quién está en fullscreen?
  • Sí, con document.fullscreenElement.
• ¿Funciona en móviles?
  • Sí, pero algunos navegadores requieren interacción táctil expresiva.
• ¿Puedo estilizar el contenido fullscreen?
  • Sí, usando :fullscreen.

Consideraciones de la API de FullScreen

Debes de tener presente que es necesario emplear los prefijos según el navegador y su versión, dicho esto el siguiente código presentado permite encontrar el prefijo que emplee el navegador del usuario; y el mismo presenta algunas similitudes con el presentado hace algunas entradas llamado: Usando la API de Visibilidad de Página en JavaScript.

Ver ejemplo Descargar