Condividi tramite

Fullscreen API

  • Articolo

You can use the fullscreen API to bring video, images, and other content to a user's full attention.

The fullscreen API

Using the new fullscreen API, you can direct a user's attention to specific elements while you hide distracting backgrounds or other apps.

Because the W3C Fullscreen specification isn't final, most browser vendors prefix the API with a unique identifier. In this case, Microsoft uses ms. It's a good idea to have a single function that requests full-screen mode across all prefixes, like most of the examples shown here. For better performance, put the W3C API name first, followed by the prefixed versions.

Note  As of Microsoft Edge, this API was unprefixed. The examples here show both the prefixed and unprefixed API. The prefixed API works in Internet Explorer 11 and the unprefixed API is intended for Microsoft Edge and beyond.

 

This table shows theJavaScript and CSS members of the Fullscreen API.

Unprefixed API Prefixed API Type Description
requestFullscreen msRequestFullscreen Method Requests full-screen display of an image, video, or other element.
exitFullscreen msExitFullscreen Method Returns an element to its original size from full-screen mode.
fullscreenElement msFullscreenElement Property Returns the top or current element that's being displayed in full-screen mode. Otherwise it returns undefined.
fullscreenEnabled msFullscreenEnabled Property Returns true if a document lets elements be displayed in full-screen mode. Otherwise it returns false.
fullscreenChange MSFullscreenChange Event Fires when an element is displayed in full-screen mode, or when it exits full-screen mode.
fullscreenError MSFullscreenError Event Fires when a full-screen display is requested of an element, but this request can't be fulfilled.
:fullscreen :-ms-fullscreen Pseudo class Enables you to set specific CSS properties based on whether an element is in full-screen mode or not.
::backdrop ::-ms-backdrop Pseudo element Enables you to set the background properties when an element is displayed in full-screen mode.
allowfullscreen allowfullscreen Attribute Enables an iframe's content to display in full-screen mode. If missing, only the iframe (and not the content within the frame) can go to full-screen mode.

 

Open an element in full-screen mode

You can open a video, image, or other element in full-screen mode by calling the requestFullscreen() method. In IE11 and Microsoft Edge, video fills the screen, while anything else (paragraph, div, or image elements) stays the same size. The rest of the screen is black unless you style the background with ::-ms-backdrop.

document.getElementById("myImage").requestFullscreen();

In IE11 and Microsoft Edge, you can prevent untrusted content from opening in full-screen mode. To do so, you must call requestFullscreen from a user-initiated event, such as a button click, rather than automatically from script. When content enters full-screen mode, IE11 and Microsoft Edge ask the user if it's okay to open it. Assuming the user says yes, the content opens, and is surrounded by a black background so that the content is the only thing visible on the screen. If the user has more than one monitor, the full-screen display fills only one monitor.

    // Initiated by a user click on an element 

    function makeFullScreen(divObj) {
       //Use the specification method before using prefixed versions
      if (divObj.requestFullscreen) {
        divObj.requestFullscreen();
      }
      else if (divObj.msRequestFullscreen) {
        divObj.msRequestFullscreen();
      }
      else if (divObj.mozRequestFullScreen) {
        divObj.mozRequestFullScreen();
      }
      else if (divObj.webkitRequestFullscreen) {
        divObj.webkitRequestFullscreen();
      } else {
        console.log("Fullscreen API is not supported");
      } 

    }

Get out of full-screen mode

Users can easily leave full-screen mode at any time by pressing ESC. To exit full-screen mode under program control, use the exitFullscreen method. Unlike requestFullscreen which applies to an element, exitFullscreen applies to the document element, so it doesn't matter which element is currently open in full-screen mode. Using this example you can open an element in full-screen mode when you click it, then return the element to its original size when you click again.

<!DOCTYPE html>
<html>
  <head>
    <title>msExitFullscreen API test</title>
  </head>
  <body>
    <div id="div1" class="fullScreen" style="width: 600px; height: 350px; background-color: yellow">
      Div1 
    </div>
    <div id="div2" class="fullScreen" style="width: 600px; height: 350px; background-color: red">
      Div2            
    </div>
    <script type="text/javascript">
      var inFullScreen = false; // flag to show when full screen

      var fsClass = document.getElementsByClassName("fullScreen");
      for (var i = 0; i < fsClass.length; i++) {
        fsClass[i].addEventListener("click", function (evt) {
          if (inFullScreen == false) {
            makeFullScreen(evt.target); // open to full screen
          } else {
            reset();
          }
        }, false);
      }

  
      function makeFullScreen(divObj) {
        if (divObj.requestFullscreen) {
          divObj.requestFullscreen();
        }
        else if (divObj.msRequestFullscreen) {
          divObj.msRequestFullscreen();
        }
        else if (divObj.mozRequestFullScreen) {
          divObj.mozRequestFullScreen();
        }
        else if (divObj.webkitRequestFullscreen) {
          divObj.webkitRequestFullscreen();
        }
        inFullScreen = true;
        return;
      }

      function reset() {
        if (document.exitFullscreen) {
          document.exitFullscreen();
        }
        else if (document.msExitFullscreen) {
          document.msExitFullscreen();
        }
        else if (document.mozCancelFullScreen) {
          document.mozCancelFullScreen();
        }
        else if (document.webkitCancelFullScreen) {
          document.webkitCancelFullScreen();
        }
        inFullScreen = false;
        return;
      }


    </script>
  </body>
</html>

Other actions can force an element out of full-screen mode, like when a user:

  • Selects a charm.
  • Snaps an instance of the browser to the side of the screen.
  • Clicks the Windows button on a tablet computer without a keyboard.
  • Removes the element currently in full screen from the Document Object Model (DOM).
  • Navigates to a new URL.
  • Swiped down from the top of the screen.
  • Swiped up from the bottom of the screen.

Note  If an element loses focus while it's in full-screen mode, it doesn't exit full-screen mode.

 

Find an element in full-screen mode

You can find the top element that's currently displayed in full-screen mode using the msFullscreenElement property on the document element. This property returns the element that's displayed in full-screen mode. If no element is currently open in full-screen mode, it returns null.

This example shows two <div> elements that when clicked, print the msFullscreenElement to their innerHTML.

<!DOCTYPE html>

<html>
  <head>
    <title>msFullscreenElement test</title>
    <style>
      /* Add a white border*/
      div {
        border: solid 2px white;
      }
    </style>
  </head>
  <body>
    <div class="fullScreen" id="div-1" style="width:600px; height:350px; background-color:yellow">
      This is Div 1
    </div><p></p>
    <div class="noFullScreen" id="div-2" style="width:600px; height:350px; background-color:red">
       This is Div 2 
    </div>

    <script>
        var inFullScreen = false;  // flag for in or out of full-screen mode. 
        // set up div that doesn't go into full-screen mode on the click event
        var nfsClass = document.getElementsByClassName("noFullScreen");
        for (var i = 0; i < nfsClass.length; i++) {
            nfsClass[i].addEventListener("click", function (evt) {
                evt.target.innerHTML = getFSWindow();
            }, false);
        }



      var fsClass = document.getElementsByClassName("fullScreen");
      for (var i = 0; i < fsClass.length; i++) {
        fsClass[i].addEventListener("click", function (evt) {
          if (inFullScreen == false) {
            makeFullScreen(evt.target); // open to full screen
            evt.target.innerHTML = getFSWindow().id;
          } else {
            reset();
          }
        }, false);
      }

     /* // set up any div with fullscreen class to go full screen when clicked
      var fsClass = document.getElementsByClassName("fullScreen");    
      for (var i = 0; i < fsClass.length; i++) {
        fsClass[i].addEventListener("click", function (evt) {
          setTimeout(reset, 10000); // Set a time out for 10 seconds
          makeFullScreen(evt.target); // open to full screen  
          evt.target.innerHTML = getFSWindow();
        }, false);
      }
 */
      //  request full screen across several browsers
      function makeFullScreen(divObj) {
        if (divObj.requestFullscreen) {
          divObj.requestFullscreen();
        }
        else if (divObj.msRequestFullscreen) {
          divObj.msRequestFullscreen();
        }
        else if (divObj.mozRequestFullScreen) {
          divObj.mozRequestFullScreen();
        }
        else if (divObj.webkitRequestFullscreen) {
          divObj.webkitRequestFullscreen();
        }
        inFullScreen = true;
        return;
      }

      //  reset full screen across several browsers
      function reset() {
        if (document.exitFullscreen) {
          document.exitFullscreen();
        }
        else if (document.msExitFullscreen) {
          document.msExitFullscreen();
        }
        else if (document.mozCancelFullScreen) {
          document.mozCancelFullScreen();
        }
        else if (document.webkitCancelFullScreen) {
           document.webkitCancelFullScreen();
        }
        inFullScreen = false;
         return;
       }

       //  get full screen element across several browsers
       function getFSWindow() {
         if (document.fullscreenElement) {
           return document.fullscreenElement;
         }
         else if (document.msFullscreenElement) {
           return document.msFullscreenElement;
         }
         else if (document.mozFullScreenElement) {
           return document.mozFullScreenElement;
         }
         else if (document.webkitFullscreenElement) {
           return document.webkitFullscreenElement;
         }
       }
    </script>
  </body>
</html>

Click the first <div> to open in full-screen mode, and the element (HTMLDivElement) is printed in the div's innerHTML. Click again to exit full-screen mode. Now, when you click the second <div>, it doesn't go into full-screen mode, and the word undefined is displayed in the <div>.

Using an iframe in full-screen mode

By default, an iframe opens in full-screen mode, but not its content. This is because the iframe is a child of the original document, but not the content which belongs to the iframe. The content of the iframe might be of unknown origin, possibly a malicious site. To allow an iframe's content to open in full-screen mode, set the allowfullscreen attribute on the iframe element.

One exception is with Adobe Flash. When a Flash control is embedded via an iframe, it always is allowed to show full screen, regardless of whether the iframe has the allowfullscreen attribute set.

This example shows how setting allowfullscreen affects how an iframe displays full-screen content. The two iframes each show the exact same webpage. When you click the buttons marked Frame 1 or Frame 2, an iframe opens in full-screen mode. The content displayed in each iframe is the same HTML page for both frames. Because only the first iframe has the allowfullscreen attribute set, only the content in the first iframe can go into full-screen mode. The second iframe's content stays original size when clicked, and an fullscreenError event is fired.

<!DOCTYPE html>
<html>
  <head>
    <title>allowfullscreen attribute test</title>
  </head>
  <body>
    <!-- include all prefixed versions of the attribute -->
    <iframe id="frame1" allowfullscreen mozallowfullscreen webkitallowfullscreen width="400" height="300" src="iframeTest.html"></iframe>
    <iframe id="frame2" width="400" height="300" src="iframeTest.html"></iframe>
    <br />
    <button onclick="makeFullScreen('frame1');">Frame 1 full screen</button>
    <button onclick="makeFullScreen('frame2');">Frame 2 full screen</button>
     
    <script type="text/javascript">
      function makeFullScreen(frame) {
        divObj = document.getElementById(frame);
        if (divObj.requestFullscreen) {
          divObj.requestFullscreen();
        }
        else if (divObj.msRequestFullscreen) {
          divObj.msRequestFullscreen();
        }
          // Moz uses camel case caps on "screen"
        else if (divObj.mozRequestFullScreen) {
          divObj.mozRequestFullScreen();
        }
        else if (divObj.webkitRequestFullscreen) {
          divObj.webkitRequestFullscreen();
        }
      }
    </script>
  </body>
</html>

This example shows the iframeTest.html test file for each iframe in the previous example.

<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8" />
    <title>fullscreen element test file</title>

  </head>
  <body>
    <div class="fullScreen" style="width:600px; height:350px; background-color:yellow">
      This is Div 1
    </div>
    <script>
      // set up any div with fullscreen class to go full screen when clicked
      var inFullScreen = false;

      var fsClass = document.getElementsByClassName("fullScreen");
      for (var i = 0; i < fsClass.length; i++) {
        fsClass[i].addEventListener("click", function (evt) {
          if (inFullScreen == false) {
            makeFullScreen(evt.target); // open to full screen
          } else {
            reset();
          }
        }, false);
      }

      document.addEventListener("MSFullscreenError", function (evt) {
        console.error("full screen error has occured " + evt.target);
      }, true);

      //  request full screen across several browsers
      function makeFullScreen(divObj) {
        if (divObj.requestFullscreen) {
          divObj.requestFullscreen();
        }
        else if (divObj.msRequestFullscreen) {
          divObj.msRequestFullscreen();
        }
        else if (divObj.mozRequestFullScreen) {
          divObj.mozRequestFullScreen();
        }
        else if (divObj.webkitRequestFullscreen) {
          divObj.webkitRequestFullscreen();
        }
        inFullScreen = true;
        return;
      }

      //  reset full screen across several browsers
      function reset() {
        if (document.exitFullscreen) {
          document.exitFullscreen();
        }
        else if (document.msExitFullscreen) {
          document.msExitFullscreen();
        }
        else if (document.mozCancelFullScreen) {
          document.mozCancelFullScreen();
        }
       else if (document.cancelFullScreen) {
         document.cancelFullScreen();
       }
       else if (document.webkitCancelFullScreen) {
         document.webkitCancelFullScreen();
       }
        inFullScreen = false;
        return;

      }   

    </script>
  </body>
</html>

Determining if full-screen mode is possible

The fullscreenEnabled property returns whether a document is capable of full-screen mode. The primary use is to check if an iframe's contentDocument has the allowfullscreen attribute set. When an iframe's contentDocument has the allowfullscreen attribute, fullscreenEnabled returns true, otherwise it returns false. fullscreenEnabled shouldn't be used to detect the fullscreen feature in general.

var isFullScreenEnabled;
if(document.fullscreenEnabled){
   isFullScreenEnabled = document.fullscreenEnabled;
}
else if(document.msFullscreenEnabled){ 
   isFullScreenEnabled = document.msFullscreenEnabled;
} 
else if (document.mozFullScreenEnabled){
   isFullScreenEnabled = document.mozFullScreenEnabled;
}

Detect full-screen mode changes

The fullscreenChange event detects when elements go into full-screen mode or leave full-screen mode. The following example prints a message to the console when an element enters or exits full-screen mode.

if (document.requestFullscreen) {
  document.addEventListener("fullscreenchange", function () {
    if (document.fullscreenElement != null) {
      console.info("Went full screen");
    } else {
      console.info("Exited full screen");
    }
  });
}
else if (document.msRequestFullscreen) {
  document.addEventListener("MSFullscreenChange", function () {
    if (document.msFullscreenElement != null) {
      console.info("Went full screen");
    } else {
      console.info("Exited full screen");
    }
  });
}
     // no info on other browsers

The fullscreenChange event is fired after an element enters or exits full-screen mode, so you can get the current state. In the example, we check the fullscreenElement to see if any elements are in full screen. If an element is in full-screen mode, the element is returned, otherwise fullscreenElement returns null.

Note  Press F12 to open the F12 developer tools when the demo runs to see the output of the example. Open the Console tab to see the messages. When the example goes into full screen mode, you'll see "Went full screen", and when it exits, you'll see "Exited full screen."

 

Catch full-screen mode errors

Full-screen mode has its own error event, fullscreenError. This event is fired when a request for full-screen mode is made, but the request can't be fulfilled. This code snippet shows a simple event handler for fullscreenError.

document.addEventListener("MSFullscreenError", function (evt) {
  console.error("full screen error has occured " + evt.target);
}, true);

Use CSS pseudo elements for full-screen styling

Using the :fullscreen CSS pseudo class and ::backdrop CSS pseudo element, you can change page element styling based on full-screen mode state. With :fullscreen, you can change the style of how an element is displayed when in full-screen mode. For most elements, like a <div>, styles you can change typically include position, color, or size.

Except for the video element, elements in full-screen mode stay the same size and are surrounded by a black background. You can change the background using the ::backdrop pseudo element. This can be an image, another color, or a border. Backgrounds for a video element displayed in letterbox or pillarbox are not affected by ::backdrop.

This example only runs in IE11, and contains no cross browser code. It initially displays a blue box. When you click the box it expands to full-screen mode, the box moves 200 pixels down and 200 pixels over, and its color changes to green. This is done by detecting full-screen mode using the :fullscreen pseudo class and applying new styles. The background around the box changes color to magenta using the ::backdrop pseudo element.

<!DOCTYPE html>

<html>
  <head>
    <title>Pseudo element test</title>
    /* this example only works in the Internet Explorer */
      <style type="text/css" media="screen">
        /* Normal view */
        #test {
          width: 200px;
          height: 200px;
          background-color: blue;
        }
   /* W3C section */    
        /* How to display when full screen */ 
       #test:-fullscreen {
         position:absolute;
         left:200px;
         top:200px;
         width: 400px;
         height: 400px;
         background-color: green;
       }
       
       /* What color to show the background */
       #test:-fullscreen::-backdrop {
         background-color: magenta;
       }
   /* Microsoft section */    
        /* How to display when full screen */ 
       #test:-ms-fullscreen {
         position:absolute;
         left:200px;
         top:200px;
         width: 400px;
         height: 400px;
         background-color: green;
       }
       
       /* What color to show the background */
       #test:-ms-fullscreen::-ms-backdrop {
         background-color: magenta;
       }       

    </style>
  </head>
  <body>    
    <div class="fullscreen" id="test">
    </div>

    <script>
      var fsClass = document.getElementsByClassName("fullscreen");

      for (var i = 0; i < fsClass.length; i++) {
        fsClass[i].addEventListener("click", function (evt) {
         makeFullScreen(evt.target); // open to full screen
        }, false);
      }

      //  request full screen across several browsers
      function makeFullScreen(divObj) {
        if (divObj.requestFullscreen) {
          divObj.requestFullscreen();
        }
        else if (divObj.msRequestFullscreen) {
          divObj.msRequestFullscreen();
        }
      }

    </script>
  </body>
</html>

How an element appears in full-screen mode varies from browser to browser. Other browsers may expand the element to fill the screen, and not support the background pseudo element.

You can use :fullscreen to change behavior so that the element expands to fill the screen, losing the black background. When the element goes into full-screen mode, you can set the CSS width and height properties to 100% to fit the window. This example expands a small box to fill the full screen. It also contains the Webkit equivalent of :fullscreen.

<!DOCTYPE html>

<html>
  <head>
    <title>ms-fullscreen pseudo class test</title>

    <style type="text/css" media="screen">
      
      /* Normal view */
      #test {
        width: 200px;
        height: 200px;
        background-color: blue;
      }
      
      /* How to display when full screen */ 
      /* Microsoft */
      #test:-ms-fullscreen {
        position:absolute;
        left:0px;
        top:0px;
        width: 100%;
        height: 100%;          
      }
      
            
      /* How to display when full screen */ 
      /* Webkit */
       #test:-webkit-full-screen {
        position:absolute;
        left:0px;
        top:0px;
        width: 100%;
        height: 100%;          
      }
   
      /* Mozilla */
       #test:-moz-full-screen {
      /* Mozilla/Gecko automatically scales to 100% */
       /* put CSS in here*/
      }

    </style>
  </head>

  <body>    
    <div class="fullscreen" id="test"></div>

    <script>
      var fsClass = document.getElementsByClassName("fullscreen");

      for (var i = 0; i < fsClass.length; i++) {
        fsClass[i].addEventListener("click", function (evt) {
          makeFullScreen(evt.target); // open to full screen
        }, false);
      }
      //  request full screen across several browsers
      function makeFullScreen(divObj) {
        if (divObj.requestFullscreen) {
          divObj.requestFullscreen();
        }
        else if (divObj.msRequestFullscreen) {
          divObj.msRequestFullscreen();
        }
        else if (divObj.mozRequestFullScreen) {
          divObj.mozRequestFullScreen();
        }
        else if (divObj.webkitRequestFullscreen) {
          divObj.webkitRequestFullscreen();
        }

      }

    </script>
  </body>
</html>

API reference

requestFullscreen

exitFullscreen

::background

:fullscreen

fullscreenChange

fullscreenError

fullscreenEnabled

fullscreenElement

allowfullscreen

Specification

Fullscreen