Entering Fullscreen with requestFullscreen()

Technical Deep Dive & Specifications

The requestFullscreen() Method Signature

element.requestFullscreen(options?: FullscreenOptions): Promise<void>

Under the WHATWG Fullscreen API specification, requestFullscreen() returns a standard JavaScript Promise:

• Resolves with undefined: When the browser successfully switches the display mode and promotes the element to the Top Layer.
• Rejects with a TypeError: When the request is denied due to lack of user gesture, iframe permission restrictions, or window state constraints.

The FullscreenOptions Dictionary & navigationUI

When invoking requestFullscreen(), you can pass an optional dictionary containing configuration parameters for the host operating system's navigation UI:

const options = {
  navigationUI: 'auto' // 'auto' | 'show' | 'hide'
};

await element.requestFullscreen(options);

+-------------------------------------------------------------------------------+
|                        `navigationUI` OPTIONS MATRIX                          |
+-------------------+-----------------------------------------------------------+
| Value             | Behavior & Operating System Hints                         |
+-------------------+-----------------------------------------------------------+
| `'auto'` (Default)| The browser decides based on device context. On mobile,   |
|                   | it typically auto-hides navigation controls until swipe.  |
|                   |                                                           |
| `'show'`          | Explicitly requests that navigation UI (e.g. software     |
|                   | back buttons, home bars, or URL bars) remain accessible.  |
|                   |                                                           |
| `'hide'`          | Explicitly requests that all software navigation elements |
|                   | be hidden for complete, uninterrupted immersion.          |
+-------------------+-----------------------------------------------------------+

[!NOTE] navigationUI is a user agent hint. The host operating system (especially iOS and Android) retains ultimate authority over whether home bars or system gesture zones can be fully suppressed.

Asynchronous Execution Pipeline

When element.requestFullscreen() is executed, the browser performs the following sequence of internal validation steps:

[1. User Gesture Check] ===(No Gesture)===> [Reject Promise (TypeError)]
          |
       (Valid)
          v
[2. Permission Policy Check] ===(Iframe Blocked)===> [Reject Promise (TypeError)]
          |
       (Allowed)
          v
[3. Promote to Top Layer] 
          |
          v
[4. Resize Viewport & Dispatch 'fullscreenchange']
          |
          v
[5. Resolve Promise (void)]

Pairing with Screen Orientation API

For immersive video players and mobile games, entering fullscreen is often paired with locking the mobile device into landscape orientation:

async function launchImmersiveGame(gameCanvas) {
  try {
    // 1. Enter fullscreen
    await gameCanvas.requestFullscreen({ navigationUI: 'hide' });

    // 2. Lock screen orientation to landscape (if supported)
    if (screen.orientation && screen.orientation.lock) {
      await screen.orientation.lock('landscape');
    }
  } catch (err) {
    console.warn('Fullscreen/Orientation request failed:', err);
  }
}

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Line 115–124 (options-panel): Provides a dynamic configuration dropdown allowing users to toggle between 'auto', 'hide', and 'show' for the navigationUI dictionary.
• Line 160–165 (options): Constructs the options object { navigationUI: 'auto' | 'hide' | 'show' } to pass as the argument to requestFullscreen().
• Line 169 (await targetElement.requestFullscreen(options)): Invokes the method on the specific targeted DOM card, returning a Promise that resolves when the browser successfully promotes the element into the Top Layer.
• Line 172–174 (catch (err)): Traps errors if the browser denies the request or if an unsupported option configuration triggers a failure.

Expected Browser Render Output

1. The user sees three interactive cards: Video Player, Game Canvas, and Analytics Dashboard.
2. Clicking "Fullscreen Video" causes only the Video Player card to expand to the full width and height of the display.
3. The surrounding web page, header, and other cards are covered by the browser's backdrop layer.
4. Pressing Escape restores the card to its original size in the gallery grid.