TheElement.requestFullscreen()method issues an asynchronous request to make the element be displayed in fullscreenmode.

It's not guaranteed that the element will be put into full screen mode. If permissionto enter full screen mode is granted, the returnedPromise will resolveand the element will receive afullscreenchange event to let it know thatit's now in full screen mode. If permission is denied, the promise is rejected and theelement receives afullscreenerror event instead. If the element has beendetached from the original document, then the document receives these events instead.

Syntax

requestFullscreen()requestFullscreen(options)

Parameters

optionsOptional

An object that controls the behavior of the transition to fullscreen mode. The available options are:

navigationUIOptional

Controls whether or not to show navigation UI while the element is in fullscreen mode.The default value is"auto", which indicates that the browser should decide what to do.

"hide"

The browser's navigation interface will be hiddenand the entire dimensions of the screen will be allocated to the display of the element.

"show"

The browser will present page navigation controls and possibly otheruser interface; the dimensions of the element (and the perceived size of the screen) will be clampedto leave room for this user interface.

"auto"

The browser will choose which of the above settings to apply.This is the default value.

screenOptionalExperimental

Specifies on which screen you want to put the element in fullscreen mode. This takes aScreenDetailed object as a value, representing the chosen screen.

Return value

APromise which is resolved with a value ofundefined whenthe transition to full screen is complete.

Exceptions

Rather than throw a traditional exception, therequestFullscreen()procedure announces error conditions by rejecting thePromise it hasreturned. The rejection handler receives one of the following exception values:

TypeError

TheTypeError exception may be delivered in any of the followingsituations:

• The document containing the element isn't fully active; that is, it's not thecurrent active document.
• The element is not contained by a document.
• The element is not permitted to use thefullscreen feature,either because ofPermissions Policy configuration or other access control features.
• The element and its document are the same node.
• The element is apopover that is already being shown viaHTMLElement.showPopover().

Security

Transient user activation is required. The user has to interact with the page or a UI element in order for this feature to work.

Usage notes

Compatible elements

An element that you wish to place into fullscreen mode has to meet a small number ofsimple requirements:

• It must be one of the standard HTML elements or<svg> or<math>.
• It isnot a<dialog> element.
• It must either be located within the top-level document or in an<iframe> which has theallowfullscreenattribute applied to it.

Additionally, any set Permissions Policies must allow the use of this feature.

Detecting fullscreen activation

You can determine whether or not your attempt to switch to fullscreen mode issuccessful by using thePromise returned byrequestFullscreen(), as seen in theexamples below.

To learn when other code has toggled fullscreen mode on and off, you should establishlisteners for thefullscreenchange event on theDocument.It's also important to listen forfullscreenchange to be aware when, forexample, the user manually toggles fullscreen mode, or when the user switchesapplications, causing your application to temporarily exit fullscreen mode.

Examples

Requesting fullscreen mode

This example toggles the<video> element in and out of fullscreen mode when theEnter orShift +F keys are pressed.The script checks whether the document is currently in fullscreen usingdocument.fullscreenElement.If the document is in fullscreen, it callsdocument.exitFullscreen() to exit.Otherwise, it callsrequestFullscreen() on the<video> element:

const video = document.querySelector("video");document.addEventListener("keydown", (event) => {  // Note that "F" is case-sensitive (uppercase):  if (event.key === "Enter" || event.key === "F") {    // Check if we're in fullscreen mode    if (document.fullscreenElement) {      document.exitFullscreen();      return;    }    // Otherwise enter fullscreen mode    video.requestFullscreen().catch((err) => {      console.error(`Error enabling fullscreen: ${err.message}`);    });  }});

<p>  The video element below shows a time-lapse of a flower blooming. You can  toggle fullscreen on and off using <kbd>Enter</kbd> or <kbd>Shift</kbd> +  <kbd>F</kbd> (uppercase "F"). The embedded document needs to have  <a    href="https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event">    focus  </a>  for the example to work.</p><video controls loop src="/shared-assets/videos/flower.mp4" width="420"></video>

body {  font-family:    "Benton Sans", "Helvetica Neue", "Helvetica", "Arial", sans-serif;  margin: 2em;}video::backdrop {  background-color: #444488;}button {  display: block;}kbd {  border: 2px solid #cdcdcd;  border-radius: 3px;  box-shadow: inset 0 -1px 0 0 #cdcdcd;  font-size: 0.825rem;  padding: 0.25rem;}

Using navigationUI

In this example, the entire document is placed into fullscreen mode by callingrequestFullscreen() on the document'sDocument.documentElement, which is the document's root<html> element.

let elem = document.documentElement;elem  .requestFullscreen({ navigationUI: "show" })  .then(() => {})  .catch((err) => {    alert(      `An error occurred while trying to switch into fullscreen mode: ${err.message} (${err.name})`,    );  });

The promise's resolve handler does nothing, but if the promise is rejected, an errormessage is displayed by callingalert().

Using the screen option

If you wanted to make the element fullscreen on the primary OS screen, you could use code like the following:

try {  const primaryScreen = (await getScreenDetails()).screens.find(    (screen) => screen.isPrimary,  );  await document.body.requestFullscreen({ screen: primaryScreen });} catch (err) {  console.error(err.name, err.message);}

TheWindow.getScreenDetails() method is used to retrieve theScreenDetails object for the current device, which containsScreenDetailed objects representing the different available screens.

Specifications

Browser compatibility

See also

• Fullscreen API
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen
• allowfullscreen