JavaScript Document fullscreenerror Event

Beginner
5 min read
Updated: Nov 2026
3 examples
Event
Decorative image with the word FULLSCREENERROR

Definition

In JavaScript, the Document fullscreenerror event fires when the browser cannot switch to fullscreen mode (MDN). Like fullscreenchange, two events are delivered: first to the failing Element, then to its owning Document.

Register a listener with addEventListener. Check readiness and browser support before you rely on this event.

Syntax

Listen for fullscreenerror. Start with this line.

JavaScript
addEventListener("fullscreenerror", fn)
CallWhat it does
addEventListener("fullscreenerror", fn)Primary signature.

Built into the browser. Listen with document.addEventListener("fullscreenerror", …) — no import required.

Library declarations
JavaScript
addEventListener("fullscreenerror", fn)

Parameters

This member has no parameters beyond those shown in the signature.

Return Value

Return ValueDescription
*Fires as a Document event (listener receives the Event object).

JavaScript Examples

Example 1 — Listen on document

MDN style: handle fullscreen failures with a Document listener.

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

document.addEventListener("fullscreenerror", handleError);
console.log("fullscreenerror listener attached");
Try It Yourself

How It Works

  1. Define a handler. Log or show UI when enter fails.
  2. Listen on document. Catches the Document delivery of the failure (MDN).
  3. Event type. A generic Event — not cancelable.
  4. Nothing yet. The handler stays idle until a request actually fails.

Example 2 — Event + Promise .catch()

Pair both signals so failures are visible even if one path is missed.

JavaScript
const panel = document.getElementById("panel");
const btn = document.getElementById("go");

document.addEventListener("fullscreenerror", () => {
  console.log("fullscreenerror fired");
});

btn.addEventListener("click", () => {
  panel.requestFullscreen().catch((err) => {
    console.log("Promise rejected:", err.name);
  });
});
Try It Yourself

How It Works

  1. Listen for the event. Document-level failure notification.
  2. Request on click. User gesture improves success odds.
  3. Catch the Promise. requestFullscreen() rejects on failure.
  4. Show feedback. Use either signal (or both) to update the UI.

Example 3 — Detect Before Offering Fullscreen

Avoid useless clicks when fullscreen is disabled or unsupported.

JavaScript
const ok =
  document.fullscreenEnabled === true &&
  typeof document.documentElement.requestFullscreen === "function";

console.log("fullscreenEnabled:", document.fullscreenEnabled);
console.log("Can try fullscreen:", ok);

if (!ok) {
  console.log("Hide the button — requests would fail");
}
Try It Yourself

How It Works

  1. Read fullscreenEnabled. Policy or embedding may disable fullscreen.
  2. Check the method. Confirm requestFullscreen exists.
  3. Gate the UI. Only show the control when both checks pass.
  4. Still listen for errors. Even “enabled” requests can fail at runtime.
Compatibility

Browser Support

Document fullscreenerror is part of the Fullscreen API. MDN marks it Limited availability (not Baseline). It is not Deprecated, Experimental, or Non-standard — still feature-detect in production.

✓ Limited availability · Not Baseline

Document fullscreenerror

Fires when the browser cannot enter fullscreen. Pair with requestFullscreen().catch(…).

Limited Feature-detect required
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
fullscreenerror Limited

Bottom line: Support mirrors the Fullscreen API. Always check fullscreenEnabled, require a user gesture, allow fullscreen in iframes, and handle both the event and Promise rejection.

Frequently Asked Questions

It fires when the browser cannot switch to fullscreen mode. As with fullscreenchange, two fullscreenerror events are fired: first on the Element that failed, then on the Document that owns that element (MDN).
No. MDN does not mark Document fullscreenerror as Deprecated, Experimental, or Non-standard. It has Limited availability (not Baseline), so feature-detect and test the browsers you care about.
Common reasons: no user gesture, iframe without allow="fullscreen", Permissions Policy blocking fullscreen, unsupported context, or the browser denying permission (MDN Fullscreen API guide).
No. MDN states this event is not cancelable. You cannot force fullscreen with preventDefault().
Either works. MDN’s Document example listens on document — handy for app-wide error UI because the second delivery reaches Document.
Success path: requestFullscreen resolves and fullscreenchange fires. Failure path: the Promise rejects and fullscreenerror fires instead of a successful mode change.

Next: pointerlockchange

Learn the Document event that fires when pointer lock is acquired or released.

pointerlockchange tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Document fullscreenchange Event JavaScript Document pointerlockchange Event