Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Browser and Web APIs

The Fullscreen API

Reference for the JavaScript Fullscreen API: requestFullscreen(), exitFullscreen(), fullscreenElement, fullscreenchange events, the :fullscreen pseudo-class and rules.

The Fullscreen API lets a page show one element, such as a video player, a game canvas or a slide, so that it fills the whole screen. You call element.requestFullscreen() on the element you want, and document.exitFullscreen() to leave. The user can always leave with the Esc key.

Only one element is fullscreen at a time, and the browser requires the request to come from a user action such as a click or key press. The page also needs permission to use fullscreen: an <iframe> must have allow="fullscreen" (or the older allowfullscreen attribute).

JavaScript
const stage = document.querySelector("#stage");
await stage.requestFullscreen();
await document.exitFullscreen();

Try it

Fullscreen is blocked inside the sandboxed frames used for these examples, so document.fullscreenEnabled is likely false here and the request is rejected. The code handles that, and works on your own page.

A fullscreen toggle button
JS Feature detection that covers the prefixes

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
element.requestFullscreen(options)
document.exitFullscreen()
document.fullscreenElement
document.fullscreenEnabled
Name Description
options.navigationUI "auto" (default), "show" or "hide": a hint for whether the browser's navigation controls stay visible.
document.fullscreenElement The element now in fullscreen, or null.
document.fullscreenEnabled true if fullscreen is available for this document.

Return value: both requestFullscreen() and exitFullscreen() return a promise that fulfills with undefined. Exceptions: the promise rejects with TypeError if the document is not allowed to use fullscreen, the element is not eligible, or there was no user gesture.

Events: fullscreenchange (fires on the element and bubbles to the document) when the state changes, and fullscreenerror when a request fails.

Usage notes

  • Needs a user gesture. Call requestFullscreen() from a click or key handler.
  • Style it with :fullscreen. The pseudo-class matches the element in fullscreen mode, and ::backdrop styles the area behind it. Elements in fullscreen often need explicit width and height of 100%.
  • Exit by the user is normal. The Esc key leaves fullscreen without calling your code, so rely on fullscreenchange to update your buttons.
  • Fullscreen the right element. Using document.documentElement fills the screen with the whole page; a specific element such as a <video> wrapper keeps your own controls visible. A <video> element on its own shows only the browser's controls.
  • iPhones have restricted support for fullscreen on elements other than video. Provide a fallback layout.
  • Not the same as the window size. Fullscreen mode is not detected by resize alone; listen for fullscreenchange.
  • Accessibility. Keep a visible control to exit fullscreen, and keep keyboard focus inside the element.

Browser support

The Fullscreen API is supported in current desktop and Android browsers. Support on iPhone for arbitrary elements is limited, so check a compatibility table. Older prefixed names (webkitRequestFullscreen) are only needed for very old browsers.