The FullSreen API in JavaScript

View example Download

The FullScreen API allows a webpage or the different elements that make it up to be presented in full screen or FullScreen. Once the browser is in this mode, the browser informs and offers different options to exit this mode.

The Fullscreen API allows you to display an HTML element—or the entire document—in full screen. Its goal is simple: eliminate interface distractions, browser bars, and other visual elements to highlight specific content (image, video, canvas, app, viewer, etc.).

In multimedia and educational projects, it is often essential. In my case, I used it for the first time to highlight large images and discovered how convenient it is to offer the user an immersive experience without relying on plugins.

What the Fullscreen API is and what it is for

The Fullscreen API allows you to display an HTML element —or the entire document— in full screen. Its goal is simple: eliminate interface distractions, browser bars, and other visual elements to highlight specific content (image, video, canvas, app, viewer, etc.).

In multimedia and educational projects, it is often essential; I used it for the first time to highlight large images and discovered how convenient it is to offer the user an immersive experience without relying on plugins.

How full-screen mode works in modern browsers

The current fullscreen mode requires three pillars:

• Explicit call to element.requestFullscreen()
• A prior user interaction (click, touch, keypress)
• Internal browser permissions

The browser creates a temporary "fullscreen context" where the selected element is the only protagonist. This mode is destroyed when the user presses Esc, performs an exit gesture, or you call document.exitFullscreen() from code.

Requirements and user gestures to activate fullscreen

The API cannot be invoked alone. Modern browsers block any request without a user gesture because it is considered a powerful action: it removes UI, maximizes the screen, and changes the visual context.

This explains why, when I was starting out, requestFullscreen() would fail for no apparent reason. The cause: I was executing it inside a callback that was not a "direct interaction." Since then, I only trigger it from buttons, links, or touch events.

How to activate full screen with JavaScript (requestFullscreen)

element.requestFullscreen() is the heart of the API. It allows any element to enter full screen: a <div>, a <video>, an <img> or even a canvas.

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

This simple call activates fullscreen mode provided the browser allows it and a user gesture exists.

When I first tested this with large images, I noticed how useful it is for capturing the user's attention. The contrast between the complete interface and the immersive mode is enormous.

How to activate full screen with JavaScript (requestFullscreen)

document.fullscreenEnabled

Before using this API, it is advisable to check if the browser allows full-screen mode, and it can also be used to check API support in the browser:

• true: If the browser allows full-screen mode.
• false: Otherwise.

if (document.fullscreenEnabled) {
 // code
}

Enter FullScreen mode: element.requestFullscreen()

This method allows a single element to obtain full screen; for example, the image presented below:

It is very useful when you want to highlight specific elements; the syntax would be as follows:

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

element.requestFullscreen() is the heart of the API. It allows any element to enter full screen: a <div>, a <video>, an <img> or even a canvas:

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

Simple example with an HTML element

In this example, you can see an HTML and the Script to view the image in fullScreen by clicking it:

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

Common problems when calling requestFullscreen

Browser without support → Solution: check

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

• Call without user interaction (very frequent).
• Call inside an iframe without adequate permissions the iframe needed allow="fullscreen".
• Blocking due to private browsing mode on some mobile browsers.

How to exit FullScreen mode (exitFullscreen): document.exitFullscreen()

Being the antagonist of the method element.requestFullscreen(), this method cancels the browser's FullScreen mode:

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

document.fullscreenElement()

This other method returns all the elements of the document that are currently in full-screen mode (NULL if no element is in this mode):

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

An example of what it might return if it were in full-screen mode:

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

Fullscreen Events: fullscreenchange and fullscreenerror

Events make the API truly useful, especially in dynamic interfaces.

How to listen when a user enters or exits full-screen mode

document.addEventListener("fullscreenchange", () => { if (document.fullscreenElement) { console.log("Entered fullscreen"); } else { console.log("Exited fullscreen"); } });

FullScreen API Events

document.fullscreenchange

This event executes every time full-screen or FullScreen mode is entered and/or exited; its syntax is as follows:

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

document.fullscreenerror

FullScreen mode can fail; for example, when trying to grant full-screen mode from an iframe.

Detect which element is in full screen (fullscreenElement)

This method is especially useful when you want to manipulate the active element. I use it a lot when I have multiple images or videos and I want to know which one is occupying the screen:

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

Best practices for handling fullscreen exit

• Ensure accessibility: offer a clear "Exit" button.
• Anticipate that the user can manually exit with Esc.
• Always listen for the fullscreenchange event.
• Avoid forcing the user to repeatedly enter: some browsers may block you.

Common errors: iframes, permissions, and restrictions

The fullscreenerror event is fired when something fails:

document.addEventListener("fullscreenerror", () => { console.error("Could not activate fullscreen"); });

The most common cause: trying to enter fullscreen from an iframe without permissions. I encountered this problem several times until I understood that the iframe must include:

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

Styles and visual behavior in full-screen mode

The :fullscreen pseudoclass allows you to define exclusive styles while an element is in full screen.

Use the CSS pseudoclass :fullscreen

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

I like to apply this when I want an image to be centered correctly without stretching.

Adaptation in images, videos, and interactive components

• Images can apply adaptive zoom.
• Videos can hide unnecessary controls.
• Canvases can be dynamically resized.
• If your interface relies heavily on relative size, also listen to resize.

Browser compatibility and modern prefixes

Current support for Chrome, Firefox, Edge, and Safari

Today, practically all modern browsers support the API without prefixes.

Except for Safari, which may still require prefixes in persistent versions of the Apple ecosystem.

Are webkitRequestFullscreen and similar still necessary?

Not anymore, but if you need historical compatibility or support for old embedded software, you can include them:

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

I used these prefixes years ago when working with very old browsers; today I almost never need them.

Complete example: entering and exiting fullscreen step by step

In this example, we have a couple of buttons to enter and exit full-screen mode:

<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
      ? "Fullscreen mode active" : 
      "You have exited fullscreen"); }); 
</script>

Frequently Asked Questions about the FullScreen API in JavaScript

• Can I put a div in full screen?
  • Yes, any element works.
• Why doesn't requestFullscreen() work?
  • Almost always due to lack of user gesture or permissions.
• Can I detect which element is in fullscreen?
  • Yes, with document.fullscreenElement.
• Does it work on mobiles?
  • Yes, but some browsers require expressive touch interaction.
• Can I style the fullscreen content?
  • Yes, using :fullscreen.

FullScreen API Considerations

You must keep in mind that it is necessary to use prefixes according to the browser and its version. That being said, the following code presented allows you to find the prefix that the user's browser uses; and it presents some similarities with the one presented a few entries ago called: Using the Page Visibility API in JavaScript.

View example Download