JavaScript Element requestFullscreen() Method

What You’ll Learn

Element.requestFullscreen() is an instance method from the Fullscreen API. It asks the browser to display an element in fullscreen mode. Learn the Promise-based flow, user-gesture rules, optional navigationUI settings, and five try-it labs.

Introduction

Video players, games, slideshows, and image galleries often need a fullscreen view. requestFullscreen() is the standard way to expand a specific element to fill the screen while keeping your page logic in JavaScript.

The call is asynchronous: it returns a Promise that resolves when fullscreen mode is active, or rejects if the browser denies the request. You typically call it from a click handler because MDN requires transient user activation.

This page is part of JavaScript Element. Related: document.fullscreenElement, document.exitFullscreen(), and the JavaScript hub.

Understanding the requestFullscreen() Method

Calling el.requestFullscreen() (or el.requestFullscreen(options)) asks the browser to make that element fullscreen. The element must be connected to a document and allowed by the page’s Permissions Policy.

• It is an instance method on Element (Fullscreen API).
• Returns a Promise that resolves with undefined on success (MDN).
• Requires user activation — start from a click or key handler.
• Works on standard HTML elements and <svg> (MDN).
• Not allowed on <dialog> elements (MDN).
• Listen for fullscreenchange to react when mode toggles.

📝 Syntax

General forms of Element.requestFullscreen (MDN):

requestFullscreen()
requestFullscreen(options)

Parameters

• options (optional) — controls transition behavior (MDN):
  • navigationUI — "auto" (default), "hide", or "show"
  • keyboardLock — "none" (default) or "browser"
  • screen — a ScreenDetailed object for multi-monitor setups

Return value

A Promise resolved with undefined when fullscreen is active (MDN).

Exceptions

• The promise may reject with TypeError if the element is not allowed, not in a document, or fullscreen is blocked by policy (MDN).

Common patterns

const box = document.getElementById("box");

// Basic — call from a click handler
box.requestFullscreen().catch(console.error);

// Toggle with document.fullscreenElement
if (document.fullscreenElement) {
  document.exitFullscreen();
} else {
  box.requestFullscreen();
}

// Show browser navigation UI
document.documentElement.requestFullscreen({ navigationUI: "show" });

Examples Gallery

Examples follow MDN Element.requestFullscreen() patterns. Use View Output or Try It Yourself for each case.

const box = document.getElementById("box");
const btn = document.getElementById("go");

btn.addEventListener("click", () => {
  box.requestFullscreen().catch((err) => {
    console.error("Fullscreen failed:", err.message);
  });
});

Promise resolves when #box is fullscreen (user click required).

const box = document.getElementById("box");

function toggleFullscreen() {
  if (document.fullscreenElement) {
    document.exitFullscreen();
    return;
  }
  box.requestFullscreen().catch(console.error);
}

document.fullscreenElement is null or points at #box.

const video = document.querySelector("video");

document.addEventListener("keydown", (event) => {
  if (event.key === "Enter" || event.key === "F") {
    if (document.fullscreenElement) {
      document.exitFullscreen();
      return;
    }
    video.requestFullscreen().catch((err) => {
      console.error(`Error: ${err.message}`);
    });
  }
});

Video expands to fullscreen; Esc exits in most browsers.

const root = document.documentElement;

root
  .requestFullscreen({ navigationUI: "show" })
  .then(() => {
    console.log("Fullscreen with navigation UI");
  })
  .catch((err) => {
    console.error(err.name, err.message);
  });

Fullscreen with navigation UI

const status = document.getElementById("status");

document.addEventListener("fullscreenchange", () => {
  if (document.fullscreenElement) {
    status.textContent = "Fullscreen: " + document.fullscreenElement.id;
  } else {
    status.textContent = "Exited fullscreen";
  }
});

Fullscreen: box  (or "Exited fullscreen")

🚀 Common Use Cases

• Expanding a video player to fill the screen.
• Immersive image galleries and slideshow presentations.
• Game canvases and interactive demos that need maximum space.
• Presentation mode for charts, dashboards, or document viewers.
• Custom fullscreen buttons alongside native video controls.
• Teaching the Fullscreen API with toggle and event-listener patterns.

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN. Limited availability (not Baseline).
• Returns a Promise, not a synchronous boolean.
• Requires transient user activation (MDN).
• Controlled by Permissions Policy fullscreen (MDN).
• Iframes need allowfullscreen (or allow="fullscreen").
• Listen for fullscreenchange and fullscreenerror on document.
• Related: document.fullscreenElement, document.exitFullscreen(), :fullscreen, JavaScript hub.

💡 Best Practices