Fullscreen API

Understanding the Fullscreen API

The Fullscreen API allows a webpage to display an element using the browser's fullscreen mode so that it can occupy the available screen area.

JavaScript can request fullscreen for an element, exit fullscreen, determine which element is currently fullscreen, and respond when fullscreen mode changes or a fullscreen request fails.

Request Fullscreen

The requestFullscreen() method asks the browser to display a particular element in fullscreen mode.

const element = document.querySelector("#example");

element.requestFullscreen();

The method returns a promise, so code can respond when the request succeeds or fails.

element.requestFullscreen()
  .then(() => {
    console.log("Fullscreen started.");
  })
  .catch((error) => {
    console.error("Fullscreen request failed:", error);
  });

The Fullscreen Element

The document.fullscreenElement property identifies the element that is currently displayed in fullscreen mode.

console.log(document.fullscreenElement);

If no element is currently fullscreen, the property returns null.

if (document.fullscreenElement) {
  console.log("An element is fullscreen.");
}

Exit Fullscreen

The document.exitFullscreen() method asks the browser to leave fullscreen mode.

document.exitFullscreen();

Like requestFullscreen(), this method returns a promise.

if (document.fullscreenElement) {
  await document.exitFullscreen();
}

Users can also leave fullscreen using browser or operating-system controls, such as the Escape key in many desktop browsers.

User Interaction Requirements

Browsers generally require a fullscreen request to occur in response to a user action, such as selecting a button.

button.addEventListener("click", () => {
  element.requestFullscreen();
});

This restriction helps prevent webpages from unexpectedly taking over the user's entire screen without an intentional action.

The fullscreenchange Event

The fullscreenchange event occurs when the document enters or leaves fullscreen mode.

document.addEventListener("fullscreenchange", () => {
  if (document.fullscreenElement) {
    console.log("Fullscreen mode is active.");
  } else {
    console.log("Fullscreen mode ended.");
  }
});

This event is useful when the interface needs to change based on whether an element is currently fullscreen.

The fullscreenerror Event

The fullscreenerror event can occur when the browser cannot complete a fullscreen request.

document.addEventListener("fullscreenerror", () => {
  console.log("Fullscreen could not be started.");
});

A request may fail because of browser restrictions, document permissions, the way the request was initiated, or the environment in which the content is displayed.

Styling Fullscreen Elements

CSS provides the :fullscreen pseudo-class for styling an element while it is displayed in fullscreen mode.

#example:fullscreen {
  background: #ffffff;
  padding: 40px;
}

This makes it possible to adjust spacing, backgrounds, sizing, or other presentation specifically for the fullscreen version of the element.

Fullscreen and Iframes

Fullscreen behavior can require additional permission when the requesting content is inside an iframe.

An iframe can use the allowfullscreen attribute to indicate that its content may request fullscreen.

<iframe src="example.html" title="Fullscreen example" allowfullscreen></iframe>

The Permissions Policy fullscreen feature can also control whether fullscreen is available to embedded content.

<iframe src="example.html" title="Fullscreen example" allow="fullscreen"></iframe>

Because your tutorial examples run inside preview frames, allowing fullscreen on the iframe is especially important for this type of demonstration.

Complete Fullscreen Example

The following example places a heading, paragraph, and button inside a container. Selecting the button displays that container in fullscreen mode.

<div id="fullscreen-box">
  <h2>Fullscreen Example</h2>
  <p>This entire area can be displayed fullscreen.</p>
  <button type="button" id="fullscreen">Enter Fullscreen</button>
</div>

<script>
const box = document.querySelector("#fullscreen-box");
const button = document.querySelector("#fullscreen");

button.addEventListener("click", async () => {
  try {
    if (!document.fullscreenElement) {
      await box.requestFullscreen();
    } else {
      await document.exitFullscreen();
    }
  } catch (error) {
    console.error("Fullscreen request failed:", error);
  }
});

document.addEventListener("fullscreenchange", () => {
  button.textContent = document.fullscreenElement
    ? "Exit Fullscreen"
    : "Enter Fullscreen";
});
</script>

The same button can both enter and exit fullscreen by checking document.fullscreenElement. The button text changes automatically when fullscreen mode changes.

Common Fullscreen API Mistakes

Best Practices

• Request fullscreen only when the user intentionally chooses it.
• Provide an obvious control for entering and leaving fullscreen mode.
• Handle rejected fullscreen promises instead of assuming the request will succeed.
• Use document.fullscreenElement to determine the current fullscreen state.
• Respond to fullscreenchange when controls or content need to reflect the current state.
• Use the :fullscreen pseudo-class when fullscreen presentation needs different styling.
• Allow fullscreen appropriately when the example or application runs inside an iframe.
• Do not interfere with the user's normal browser or keyboard controls for leaving fullscreen.
• Use fullscreen when it provides a genuine benefit, such as viewing media, presentations, games, or detailed interactive content.

Summary

The Fullscreen API allows an element to occupy the browser's fullscreen display using requestFullscreen(). The current fullscreen element is available through document.fullscreenElement, while document.exitFullscreen() returns the document to its normal display.

Fullscreen requests normally require user interaction and can be monitored with fullscreenchange and fullscreenerror events. This completes the Web APIs section of the HTML Tutorial.