JavaScript Element fullscreenerror Event

What You’ll Learn

The fullscreenerror event fires when the browser cannot switch to fullscreen. Learn onfullscreenerror, why requests fail, 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).

Treat this event as your UX safety net: show a friendly message, offer a non-fullscreen fallback, and keep the rest of the app working. MDN marks it as Limited availability (not Baseline)—feature-detect and test.

Understanding fullscreenerror

An instance event that answers: “Did the fullscreen mode change fail for this element?”

• 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 — onfullscreenerror or addEventListener("fullscreenerror", ...).
• Limited availability on MDN (not Baseline)—test carefully.

📝 Syntax

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

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

onfullscreenerror = (event) => { };

Event type

A generic Event. Not cancelable.

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 Element: fullscreenerror event. 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);
}

requestor.addEventListener("fullscreenerror", handleError);
// or
requestor.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");

el.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");

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

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

Promise rejected: ...
Event: fullscreenerror

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

el.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");
const btn = document.getElementById("go");

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

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

btn.addEventListener("click", () => {
  el.requestFullscreen().catch(() => {
    // Event handler also updates UI; catch avoids unhandled rejection.
  });
});

Fullscreen blocked here. Using a large windowed layout instead.

🚀 Common Use Cases

• Show “Fullscreen not available” toasts in video / game UIs.
• Fall back to a CSS maximized panel when the API is blocked.
• Log analytics for permission / iframe / gesture failures.
• Teach why user gestures matter for privileged browser APIs.
• Central document-level error handlers for multi-widget apps.

🔧 How It Works

📝 Notes

• MDN: Limited availability (not Baseline)—test the browsers you support.
• Not Deprecated, Experimental, or Non-standard — no status banner required.
• The event is not cancelable.
• Handle both fullscreenerror and Promise .catch().
• Related learning: fullscreenchange, gesturechange, addEventListener(), JavaScript hub.

💡 Best Practices