# How to use Fullscreen API

Have you ever wondered how the fullscreen button on web video players works? The answer to that is quite simple, they leverage the browser's Fullscreen API.

The Fullscreen API augments the Document and Element interfaces with a few methods, properties, and event handlers to allow turning on or off the fullscreen mode for a specific Element.

---

**TLDR;**  
`Document.fullscreenEnabled` - tells you if fullscreen mode is available  
`Element.requestFullscreen()` - engage fullscreen mode for an element  
`Document.exitFullscreen()` - switch back to windowed mode  
`Document.fullscreenElement` - returns the element which is currently fullscreen or null  
`fullscreenchange` - event emitted by an element when it switches to fullscreen or back  
`fullscreenerror` - event emitted by an element when it errors while engaging fullscreen  
`:fullscreen` - CSS pseudo-class that targets the fullscreen element

---

Since the API is not that vast let's go straight to how to use it.

Before calling any method is recommended to first check if the functionality is available, you do that by accessing `document.fullscreenEnabled` boolean property which indicates whether the fullscreen mode is available.

```javascript
if (document.fullscreenEnabled) {
    console.log("Your browser can use fullscreen right now");
    ...
} else {
    console.log("Your browser cannot use fullscreen right now");
    ...
}
```

Knowing that the functionality is available next step would be to engage it. Engaging is done by calling `requestFullscreen` on the `Element` you want to become fullscreen.

```javascript
let element = document.querySelector("videoPlayer");

element.requestFullscreen()
    .then(() => console.log("Fullscreen engaged successfully"))
    .catch(err => console.log(`Error engaging fullscreen ${err.message}`));
```

`requestFullscreen` returns a `Promise` which on completion resolves with `undefined` and on error it rejects the promise with the specific error.  
It is worth noting that only elements that meet the following requirements can engage fullscreen mode:

* It's not a `dialog` element
    
* It must be located in the top-level document, or inside an `iframe` with the `allowfullscreen` attribute.
    

To exit, the user can press the `F11` or `Esc` keys, to exit programmatically call the `exitFullscreen` method of Document.

```javascript
if (document.fullscreenElement) {
  document
    .exitFullscreen()
    .then(() => console.log("Exited from fullscreen mode"))
    .catch((err) => console.error(err));
}
```

Same as `requestFullscreen` the `exitFullscreen` method returns a `Promise` which resolves with undefined and on error it rejects with the specific error.  
Notice the use of `fullscreenElement` property in the example above, this property contains the `Element` that is currently in fullscreen or `null` if none is.

For more flexibility, there are two noncancellable events emitted by the targeted Element:

* `fullscreenchange` - emitted by an Element immediately after it switches into or out of fullscreen.
    
* `fullscreenerror` - emitted by an Element when the browser for whatever reason fails to enter fullscreen mode.
    

To help with styling, the `:fullscreen` pseudo-class matches the element that is currently in fullscreen allowing you to adjust the layout when the element switches to fullscreen and back.