JavaScript Document fullscreenerror Event

What You’ll Learn

The Document fullscreenerror event fires when the browser cannot switch to fullscreen. Learn why MDN delivers two events (Element, then Document), how to use document.onfullscreenerror, how it pairs with requestFullscreen() Promise rejection, and five try-it labs.

Introduction

Fullscreen is powerful—and often restricted. If requestFullscreen() is denied, the element does not go fullscreen. Instead you get a fullscreenerror event (and usually a rejected Promise).

Per MDN, two fullscreenerror events fire: the first on the Element that failed to change modes, and the second on the Document that owns that element. Listening on document is the natural place for app-wide error UI.

Understanding fullscreenerror

A Document event that answers: “Did a fullscreen mode change fail?”

• Fires when the browser cannot switch into (or sometimes out of) fullscreen.
• Two deliveries — first to the Element, then to its Document (like fullscreenchange).
• Not cancelable — you cannot force fullscreen by calling preventDefault().
• Event type — a plain Event (no rich error code on the event itself).
• Handler — document.onfullscreenerror or document.addEventListener("fullscreenerror", ...).
• Limited availability on MDN (not Baseline)—test carefully.

📝 Syntax

Use the event name with addEventListener, or set the handler property on document:

addEventListener("fullscreenerror", (event) => { });

onfullscreenerror = (event) => { };

Event type

A generic Event. Not cancelable.

MDN Document example

const requestor = document.querySelector("div");

function handleError(event) {
  console.error("an error occurred changing into fullscreen");
  console.log(event);
}

document.addEventListener("fullscreenerror", handleError);
// or
document.onfullscreenerror = handleError;

requestor.requestFullscreen();

Success vs failure path

⚠️ Why Fullscreen Requests Fail

• No user gesture — call from a click/key handler, not a bare timer.
• Iframe policy — nested frames often need allow="fullscreen".
• Permissions Policy — the page or parent may block the fullscreen feature.
• Unsupported content — some element types / plugins cannot go fullscreen.
• Detached nodes — if the element left the document, events may go to the Document instead.

See MDN’s Guide to the Fullscreen API for more failure cases.

⚖️ fullscreenerror vs fullscreenchange

Examples Gallery

Examples follow MDN Document: fullscreenerror event and listen on document. Some labs intentionally trigger failures (for example calling without a user gesture).

const requestor = document.querySelector("div");

function handleError(event) {
  console.error("an error occurred changing into fullscreen");
  console.log(event);
}

document.addEventListener("fullscreenerror", handleError);
// or
document.onfullscreenerror = handleError;

requestor.requestFullscreen();

an error occurred changing into fullscreen
(Event object logged — request may fail without a user gesture)

const el = document.getElementById("fs");
const out = document.getElementById("out");

document.onfullscreenerror = () => {
  out.textContent = "fullscreenerror: could not change mode";
};

document.getElementById("bad").addEventListener("click", () => {
  // Still may fail in some environments (iframe / policy)
  el.requestFullscreen();
});

fullscreenerror: could not change mode

const el = document.getElementById("fs");
const out = document.getElementById("out");

document.addEventListener("fullscreenerror", () => {
  out.textContent = "Event: fullscreenerror (on document)";
});

document.getElementById("go").addEventListener("click", () => {
  el.requestFullscreen().catch((err) => {
    out.textContent =
      "Promise rejected: " + (err && err.message ? err.message : String(err));
  });
});

Event: fullscreenerror (on document)
(and/or Promise rejected with a message)

const el = document.getElementById("fs");
const out = document.getElementById("out");

document.addEventListener("fullscreenerror", () => {
  out.textContent = "fullscreenerror (likely no user gesture / policy)";
});

document.getElementById("arm").addEventListener("click", () => {
  out.textContent = "Calling requestFullscreen in 500ms without a gesture...";
  setTimeout(() => {
    el.requestFullscreen().catch(() => {
      out.textContent += "\nPromise also rejected.";
    });
  }, 500);
});

Calling requestFullscreen in 500ms without a gesture...
fullscreenerror (likely no user gesture / policy)
Promise also rejected.

const el = document.getElementById("fs");
const msg = document.getElementById("msg");

document.addEventListener("fullscreenerror", () => {
  msg.textContent =
    "Fullscreen blocked here. Using a large windowed layout instead.";
  el.classList.add("is-maximized");
});

document.addEventListener("fullscreenchange", () => {
  if (document.fullscreenElement) {
    msg.textContent = "Fullscreen OK";
    el.classList.remove("is-maximized");
  }
});

document.getElementById("go").addEventListener("click", () => {
  el.requestFullscreen().catch(() => {});
});

Fullscreen blocked here. Using a large windowed layout instead.

🚀 Common Use Cases

• Toast / banner when a fullscreen button is denied.
• Falling back to a maximized in-page layout.
• Logging analytics for fullscreen permission failures.
• Teaching why user gestures matter for privileged APIs.
• One Document listener covering errors from any fullscreen widget.

🔧 How It Works

📝 Notes

• MDN: Limited availability (not Baseline)—test the browsers you support.
• Not Deprecated, Experimental, or Non-standard—no status banner required.
• Not cancelable; pair with Promise .catch() for richer messages.
• Two deliveries: Element first, then Document.
• Related learning: fullscreenchange, exitFullscreen(), fullscreenEnabled, JavaScript hub.

💡 Best Practices