Fullscreen API

HTML5 Fullscreen API Overview

The HTML5 Fullscreen API allows web applications to display an HTML element using the entire screen. Instead of showing only inside the browser window, an element such as a video, image, presentation, game, chart, or canvas can occupy the user's entire display for a more immersive experience.

The Fullscreen API is commonly used in video players, image galleries, presentations, online games, dashboards, data visualizations, maps, document viewers, code editors, and Progressive Web Apps.

Enter Fullscreen

<button id="open">
  Enter Fullscreen
</button>

<div id="viewer">
  Fullscreen Content
</div>

<script>
const viewer =
  document.querySelector("#viewer");

document
  .querySelector("#open")
  .addEventListener("click", async () => {

    await viewer.requestFullscreen();

  });
</script>

Calling requestFullscreen() requests fullscreen mode for the selected HTML element. Most browsers require this method to be triggered from a user action such as a button click.

Exit Fullscreen

document
  .querySelector("#exit")
  .addEventListener("click", async () => {

    if (document.fullscreenElement) {

      await document.exitFullscreen();

    }

  });

exitFullscreen() returns the browser to normal viewing mode.

Feature Detection

if (
  "requestFullscreen" in
  document.documentElement
) {

  console.log(
    "Fullscreen supported."
  );

} else {

  console.log(
    "Fullscreen not supported."
  );

}

Always check for browser support before attempting to enter fullscreen mode.

Fullscreen Methods and Properties

Fullscreen Events

Detect Fullscreen Changes

document.addEventListener(
  "fullscreenchange",
  () => {

    if (
      document.fullscreenElement
    ) {

      console.log(
        "Entered fullscreen."
      );

    } else {

      console.log(
        "Exited fullscreen."
      );

    }

  }
);

This event is useful for updating button text, icons, layouts, or other UI elements when fullscreen mode changes.

Toggle Fullscreen

const viewer =
  document.querySelector("#viewer");

async function toggleFullscreen() {

  if (
    document.fullscreenElement
  ) {

    await document.exitFullscreen();

  } else {

    await viewer.requestFullscreen();

  }

}

Toggle functions provide a cleaner user experience by allowing the same button to enter and exit fullscreen.

Fullscreen Video Example

const video =
  document.querySelector("video");

document
  .querySelector("#fullscreen")
  .addEventListener("click", () => {

    video.requestFullscreen();

  });

Many custom video players use the Fullscreen API instead of relying on the browser's default controls.

Fullscreen Canvas Example

const canvas =
  document.querySelector("canvas");

document
  .querySelector("#play")
  .addEventListener("click", () => {

    canvas.requestFullscreen();

  });

HTML5 games often display the canvas in fullscreen mode for a more immersive gaming experience.

Handle Fullscreen Errors

document.addEventListener(
  "fullscreenerror",
  () => {

    console.error(
      "Unable to enter fullscreen."
    );

  }
);

Fullscreen requests may fail if they are not triggered by a user gesture or if browser security restrictions prevent fullscreen mode.

Browser Behavior

Common Fullscreen API Use Cases

• Video streaming platforms
• HTML5 games
• Presentation software
• Image galleries
• Interactive dashboards
• Maps and GIS applications
• Code editors
• Progressive Web Apps

Fullscreen API Best Practices

• Request fullscreen only after a user gesture.
• Always provide an Exit Fullscreen button.
• Handle fullscreenchange events.
• Gracefully handle request failures.
• Provide keyboard shortcuts such as ESC.
• Adjust layouts for fullscreen mode.
• Test behavior across desktop and mobile browsers.
• Use feature detection before calling the API.

Accessibility Considerations

• Provide a clearly visible Exit Fullscreen button.
• Maintain keyboard accessibility.
• Do not trap keyboard focus.
• Announce fullscreen changes when appropriate.
• Ensure sufficient color contrast for controls.
• Support keyboard-only navigation.

Common Fullscreen API Mistakes

• Calling requestFullscreen() without user interaction.
• Ignoring browser support.
• Not handling rejected Promises.
• Forgetting an Exit Fullscreen option.
• Not responding to fullscreenchange events.
• Breaking layouts after entering fullscreen.
• Ignoring accessibility requirements.
• Assuming every browser behaves identically.

Fullscreen API vs CSS Fullscreen Layout

Key Takeaways

• The Fullscreen API displays an element using the entire screen.
• Use requestFullscreen() to enter fullscreen.
• Use document.exitFullscreen() to exit.
• Listen for fullscreenchange to update your UI.
• Most browsers require a user gesture before entering fullscreen.
• Always provide accessible controls and graceful fallbacks.