Fullscreen API

The Fullscreen API has no interfaces of its own. Instead, it augments several other interfaces to add the methods, properties, and event handlers needed to provide full-screen functionality. These are listed in the following sections.

The Fullscreen API adds methods to the Document and Element interfaces to allow turning off and on full-screen mode.

Document.exitFullscreen() (en-US)

Requests that the user agent switch from full-screen mode back to windowed mode. Returns a Promise which is resolved once full-screen mode has been completely shut off.

Element.requestFullscreen() (en-US)

Asks the user agent to place the specified element (and, by extension, its descendants) into full-screen mode, removing all of the browser's UI elements as well as all other applications from the screen. Returns a Promise which is resolved once full-screen mode has been activated.

The Document interface provides properties that can be used to determine if full-screen mode is supported and available, and if full-screen mode is currently active, which element is using the screen.

DocumentOrShadowRoot.fullscreenElement (en-US)

The fullscreenElement property tells you the Element that's currently being displayed in full-screen mode on the DOM (or shadow DOM). If this is null, the document is not in full-screen mode.

Document.fullscreenEnabled (en-US)

The fullscreenEnabled property tells you whether or not it is possible to engage full-screen mode. This is false if full-screen mode is not available for any reason (such as the "fullscreen" feature not being allowed, or full-screen mode not being supported).

The Fullscreen API defines two events which can be used to detect when full-screen mode is turned on and off, as well as when errors occur during the process of changing between full-screen and windowed modes. Event handlers for these events are available on the Document and Element interfaces.

Event handlers on documents

Document.onfullscreenchange (en-US)

An event handler for the fullscreenchange (en-US) event that's sent to a Document when that document is placed into full-screen mode, or when that document exits full-screen mode. This handler is called only when the entire document is presented in full-screen mode.

Document.onfullscreenerror (en-US)

An event handler for the fullscreenerror (en-US) event that gets sent to a Document when an error occurs while trying to enable or disable full-screen mode for the entire document.

Event handlers on elements

Element.onfullscreenchange (en-US)

An event handler which is called when the fullscreenchange (en-US) event is sent to the element, indicating that the element has been placed into, or removed from, full-screen mode.

Element.onfullscreenerror (en-US)

An event handler for the fullscreenerror (en-US) event when sent to an element which has encountered an error while transitioning into or out of full-screen mode.

Document.fullscreen (en-US) Устарело

A Boolean value which is true if the document has an element currently being displayed in full-screen mode; otherwise, this returns false.

Примечание: Use the fullscreenElement (en-US) property on the Document or ShadowRoot (en-US) instead; if it's not null, then it's an Element currently being displayed in full-screen mode.

The Fullscreen API defines two events which can be used to detect when full-screen mode is turned on and off, as well as when errors occur during the process of changing between full-screen and windowed modes.

fullscreenchange (en-US)

Sent to a Document or Element when it transitions into or out of full-screen mode.

fullscreenerror (en-US)

Sent to a Document or Element if an error occurs while attempting to switch it into or out of full-screen mode.

FullscreenOptions (en-US)

Provides optional settings you can specify when calling requestFullscreen() (en-US).

The availability of full-screen mode can be controlled using Feature Policy. The full-screen mode feature is identified by the string "fullscreen", with a default allow-list value of "self", meaning that full-screen mode is permitted in top-level document contexts, as well as to nested browsing contexts loaded from the same origin as the top-most document.

See Using Feature Policy to learn more about using Feature Policy to control access to an API.

Users can choose to exit full-screen mode simply by pressing the ESC (or F11) key, rather than waiting for the site or app to programmatically do so. Make sure you provide, somewhere in your user interface, appropriate user interface elements that inform the user that this option is available to them.

In this example, a video is presented in a web page. Pressing the Return or Enter key lets the user toggle between windowed and full-screen presentation of the video.

View Live Examples

When the page is loaded, this code is run to set up an event listener to watch for the Enter key.

document.addEventListener("keypress", function(e) {
  if (e.keyCode === 13) {
    toggleFullScreen();
  }
}, false);

This code is called by the event handler above when the user hits the Enter key.

function toggleFullScreen() {
  if (!document.fullscreenElement) {
      document.documentElement.requestFullscreen();
  } else {
    if (document.exitFullscreen) {
      document.exitFullscreen();
    }
  }
}

This starts by looking at the value of the document's fullscreenElement attribute. In a real-world deployment, at this time, you'll want to check for prefixed versions of this (mozFullScreenElement, msFullscreenElement, or webkitFullscreenElement, for example). If the value is null, the document is currently in windowed mode, so we need to switch to full-screen mode; otherwise, it's the element that's currently in full-screen mode. Switching to full-screen mode is done by calling Element.requestFullscreen() (en-US) on the <video> element.

If full-screen mode is already active (fullscreenElement is not null), we call exitFullscreen() (en-US) on the document to shut off full-screen mode.

• Using full-screen mode
• Element.requestFullscreen() (en-US)
• Document.exitFullscreen() (en-US)
• Document.fullscreen (en-US)
• Document.fullscreenElement (en-US)
• :fullscreen, ::backdrop
• allowfullscreen (en-US)