Guide to the Fullscreen API
===========================

This article demonstrates how to use the Fullscreen API to place a given element into fullscreen mode, as well as how to detect when the browser enters or exits fullscreen mode.

Activating fullscreen mode
--------------------------

Given an element that you'd like to present in fullscreen mode (such as a `<video>`, for example), you can present it in fullscreen mode by calling its `requestFullscreen()` method.

Let's consider this `<video>` element:


```html
<video controls id="myvideo">
  <source src="somevideo.webm"></source>
  <source src="somevideo.mp4"></source>
</video>
```


We can put that video into fullscreen mode as follows:


```js
const elem = document.getElementById("myvideo");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
}
```


This code checks for the existence of the `requestFullscreen()` method before calling it.

### Notification

When fullscreen mode is successfully engaged, the document which contains the element receives a `fullscreenchange` event. When fullscreen mode is exited, the document again receives a `fullscreenchange` event. Note that the `fullscreenchange` event doesn't provide any information itself as to whether the document is entering or exiting fullscreen mode, but if the document has a non null `fullscreenElement`, you know you're in fullscreen mode.

### When a fullscreen request fails

It's not guaranteed that you'll be able to switch into fullscreen mode. For example, `<iframe>` elements have the `allowfullscreen` attribute in order to opt-in to allowing their content to be displayed in fullscreen mode. In addition, certain kinds of content, such as windowed plug-ins, cannot be presented in fullscreen mode. Attempting to put an element which can't be displayed in fullscreen mode (or the parent or descendant of such an element) won't work. Instead, the element which requested fullscreen will receive a `mozfullscreenerror` event. When a fullscreen request fails, Firefox will log an error message to the Web Console explaining why the request failed. In Chrome and newer versions of Opera however, no such warning is generated.

**Note:** Fullscreen requests need to be called from within an event handler or otherwise they will be denied.

Getting out of full screen mode
-------------------------------

The user always has the ability to exit fullscreen mode of their own accord; see Things your users want to know. You can also do so programmatically by calling the `Document.exitFullscreen()` method.

Other information
-----------------

The `Document` provides some additional information that can be useful when developing fullscreen web applications:

`Document.fullscreenElement` / `ShadowRoot.fullscreenElement`

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

`Document.fullscreenEnabled`

The `fullscreenEnabled` property tells you whether or not the document is currently in a state that would allow fullscreen mode to be requested.

### Viewport scaling in mobile browsers

Some mobile browsers while in fullscreen mode ignore viewport meta-tag settings and block user scaling; for example: a "pinch to zoom" gesture may not work on a page presented in fullscreen mode — even if, when not in fullscreen mode, the page can be scaled using pinch to zoom.

Things your users want to know
------------------------------

You'll want to be sure to let your users know that they can press the `Esc` key (or `F11`) to exit fullscreen mode.

In addition, navigating to another page, changing tabs, or switching to another application (using, for example, `Alt`-`Tab`) while in fullscreen mode exits fullscreen mode as well.

Example
-------

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

View Live Examples

### Watching for the Enter key

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


```js
document.addEventListener(
  "keydown",
  (e) => {
    if (e.key === "Enter") {
      toggleFullScreen();
    }
  },
  false,
);
```

### Toggling fullscreen mode

This code is called when the user hits the `Enter` key, as seen above.


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


This starts by looking at the value of the `fullscreenElement` attribute on the `document`. If it's `null`, the document is currently in windowed mode, so we need to switch to fullscreen mode. Switching to fullscreen mode is done by calling `element.requestFullscreen()`.

If fullscreen mode is already active (`fullscreenElement` is non-`null`), we call `document.exitFullscreen()`.

Prefixing
---------

For the moment not all browsers are implementing the unprefixed version of the API (for vendor agnostic access to the Fullscreen API you can use Fscreen). Here is the table summarizing the prefixes and name differences between them:

| Standard | WebKit (Safari) / Blink (Chrome & Opera) / Edge | Gecko (Firefox) | Internet Explorer |
| --- | --- | --- | --- |
| `Document.fullscreen` 
Deprecated
 | `webkitIsFullScreen` | `mozFullScreen` | - |
| `Document.fullscreenEnabled` | `webkitFullscreenEnabled` | `mozFullScreenEnabled` | `msFullscreenEnabled` |
| `Document.fullscreenElement` | `webkitFullscreenElement` | `mozFullScreenElement` | `msFullscreenElement` |
| `Document.exitFullscreen()` | `webkitExitFullscreen()` | `mozCancelFullScreen()` | `msExitFullscreen()` |
| `Element.requestFullscreen()` | `webkitRequestFullscreen()` | `mozRequestFullScreen()` | `msRequestFullscreen()` |

Specifications
--------------

| Specification |
| --- |
| Fullscreen API Standard # ref-for-dom-document-fullscreenenabled① |
| Fullscreen API Standard # dom-document-fullscreen |

Browser compatibility
---------------------

### api.Document.fullscreenEnabled

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Document.fullscreen

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using fullscreen mode
* `Element.requestFullscreen()`
* `Document.exitFullscreen()`
* `Document.fullscreen`
* `Document.fullscreenElement`
* `:fullscreen`, `::backdrop`
* `allowfullscreen`