Imagine you're in a classroom with a laptop and a massive projector. Most of the time, you're just typing away on your small screen. But when it's time for the actual presentation, you hit a switch and suddenly, one specific slide fills the entire wall. You aren't moving the laptop; you're just telling the system, "Take this one piece of content and make it the only thing anyone sees."

That's exactly what the Fullscreen API does for your web app. The "laptop" is your browser window, the "slide" is a DOM element (like a <video> or a <div>), and the "switch" is a JavaScript method that tells the browser to ignore everything else and expand that element to the edges of the physical monitor.

Grabbing the whole screen

To make an element go fullscreen, you call requestFullscreen() on that specific element. It's an asynchronous method that returns a Promise, which is important if you're handling errors (like if the browser blocks the request).

const galleryImage = document.querySelector('.hero-image');

async function enterCinemaMode() {
  try {
    await galleryImage.requestFullscreen();
    console.log("We're in the big screen now!");
  } catch (err) {
    console.error(`Error attempting to enable full-screen mode: ${err.message}`);
  }
}

One thing to notice here: I called this on galleryImage. If you call it on a <div> that contains a video and some captions, the entire container goes fullscreen. If you call it only on the video, the captions will disappear from view. Choose your target wisely.

The "User Gesture" hurdle

Now, here is where most developers hit a wall. You cannot just trigger fullscreen on page load. If websites could do that, every annoying ad would suddenly take over your entire monitor the second you landed on a page. Absolute chaos.

The browser requires a "user gesture"—meaning a click, a keypress, or a touch. If you try to call requestFullscreen() inside a setTimeout or an API fetch response without a direct user trigger, the browser will throw a security error and refuse to comply. Always tie your fullscreen logic to a button or a specific interaction.

Getting back to reality

Exiting fullscreen is slightly different. While you requested fullscreen on a specific element, you exit fullscreen on the document object itself. You don't tell the image to shrink; you tell the browser to stop the fullscreen mode entirely.

function exitCinemaMode() {
  if (document.fullscreenElement) {
    document.exitFullscreen();
  }
}

I usually check for document.fullscreenElement first. This property is your best friend—it returns the element that is currently in fullscreen mode, or null if the browser is in normal windowed mode. It's the easiest way to toggle your UI buttons between "Enter Fullscreen" and "Exit Fullscreen."

Listening for the switch

Since users can exit fullscreen by hitting the Esc key, your JavaScript needs to know when that happens so you can update your UI. You don't want a button that says "Enter Fullscreen" when the user is already staring at a full-screen image.

We use the fullscreenchange event for this. It's fired on the document whenever the state changes, regardless of whether it was triggered by your code or the Esc key.

document.addEventListener('fullscreenchange', () => {
  if (document.fullscreenElement) {
    console.log("The user is now in fullscreen mode.");
    // Update your button text to "Exit"
  } else {
    console.log("The user returned to the window.");
    // Update your button text to "Enter"
  }
});

📋 Practical Task

Build a Cinematic Image Toggle

Create a simple page with an image and a button. Your task is to implement a "Cinema Mode" toggle. The logic should be as follows:

• When the button is clicked, if the image is not in fullscreen, make it go fullscreen.
• If the image is already in fullscreen, exit fullscreen mode.
• The button text must dynamically change between "Go Cinematic" and "Back to Page" based on the current state.
• Crucial: The button text must update correctly even if the user presses the Esc key to exit fullscreen, not just when they click the button.