diff --git a/files/en-us/web/api/element/requestfullscreen/index.md b/files/en-us/web/api/element/requestfullscreen/index.md index c2d113eccf721a9..46d29b30b3f8328 100644 --- a/files/en-us/web/api/element/requestfullscreen/index.md +++ b/files/en-us/web/api/element/requestfullscreen/index.md @@ -8,16 +8,7 @@ browser-compat: api.Element.requestFullscreen {{APIRef("Fullscreen API")}} -The **`Element.requestFullscreen()`** -method issues an asynchronous request to make the element be displayed in fullscreen -mode. - -It's not guaranteed that the element will be put into full screen mode. If permission -to enter full screen mode is granted, the returned {{JSxRef("Promise")}} will resolve -and the element will receive a {{domxref("Element/fullscreenchange_event", "fullscreenchange")}} event to let it know that -it's now in full screen mode. If permission is denied, the promise is rejected and the -element receives a {{domxref("Element/fullscreenerror_event", "fullscreenerror")}} event instead. If the element has been -detached from the original document, then the document receives these events instead. +The **`requestFullscreen()`** method of the {{domxref("Element")}} interface issues an asynchronous request to display the element in fullscreen mode. ## Syntax @@ -29,76 +20,125 @@ requestFullscreen(options) ### Parameters - `options` {{optional_inline}} - - : An object that controls the behavior of the transition to fullscreen mode. The available options are: + - : An object that controls the behavior of the transition to fullscreen mode. + The available options are: + - `keyboardLock` {{optional_inline}} + - : Controls the selected keyboard lock mode. + - `"none"` + - : No keyboard lock is applied. + This is the default mode. + - `"browser"` + - : Browser keyboard lock mode is applied. + In this mode, the browser forwards keyboard events to the application that would normally be handled by browser or system code. + Applications should intercept events for the keys and key combinations they want to use, and call [`preventDefault()`](/en-US/docs/Web/API/Event/preventDefault) to cancel any default actions. + + Note that some browsers may disable the default action for some keys, such as the key that is normally used to exit fullscreen mode; this is not guaranteed, so you should always call `preventDefault()`. + Browsers are also encouraged to provide a mechanism to exit fullscreen mode with keyboard lock. + + For more information see the [Keyboard locking](#keyboard_locking) section below. + - `navigationUI` {{optional_inline}} - : Controls whether or not to show navigation UI while the element is in fullscreen mode. The default value is `"auto"`, which indicates that the browser should decide what to do. - `"hide"` - - : The browser's navigation interface will be hidden - and the entire dimensions of the screen will be allocated to the display of the element. + - : The browser's navigation interface will be hidden and the entire dimensions of the screen will be allocated to the display of the element. - `"show"` - - : The browser will present page navigation controls and possibly other - user interface; the dimensions of the element (and the perceived size of the screen) will be clamped - to leave room for this user interface. + - : The browser will present page navigation controls and possibly other user interface; the dimensions of the element (and the perceived size of the screen) will be clamped to leave room for this user interface. - `"auto"` - : The browser will choose which of the above settings to apply. This is the default value. - `screen` {{optional_inline}} {{experimental_inline}} - - : Specifies on which screen you want to put the element in fullscreen mode. This takes a {{domxref("ScreenDetailed")}} object as a value, representing the chosen screen. + - : Specifies on which screen you want to put the element in fullscreen mode. + This takes a {{domxref("ScreenDetailed")}} object as a value, representing the chosen screen. ### Return value -A {{JSxRef("Promise")}} which is resolved with a value of `undefined` when -the transition to full screen is complete. +A {{JSxRef("Promise")}} which is resolved with a value of `undefined` when the transition to full screen is complete, or rejects with an exception. ### Exceptions -_Rather than throw a traditional exception, the `requestFullscreen()` -procedure announces error conditions by rejecting the `Promise` it has -returned. The rejection handler receives one of the following exception values:_ +On error the returned `Promise` rejects with one of the following values: - {{jsxref("TypeError")}} - - : The `TypeError` exception may be delivered in any of the following - situations: - - The document containing the element isn't fully active; that is, it's not the - current active document. + - : The `TypeError` exception may be delivered in any of the following situations: + - The document containing the element isn't fully active; that is, it's not the current active document. - The element is not contained by a document. - - The element is not permitted to use the `fullscreen` feature, - either because of [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) configuration or other access control features. + - The element is not permitted to use the `fullscreen` feature, either because of [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) configuration or other access control features. - The element and its document are the same node. - The element is a [popover](/en-US/docs/Web/API/Popover_API) that is already being shown via {{domxref("HTMLElement.showPopover()")}}. -## Security +- `NotSupportedError` {{domxref("DOMException")}} + - : The passed `options.keyboardLock` parameter is not supported by the browser. + +## Description + +The **`requestFullscreen()`** method issues an asynchronous request to display the element in fullscreen mode. + +The method requires permission. -[Transient user activation](/en-US/docs/Web/Security/Defenses/User_activation) is required. The user has to interact with the page or a UI element in order for this feature to work. +- If permission to enter full screen mode is granted, the returned {{JSxRef("Promise")}} will resolve and the element will receive a {{domxref("Element/fullscreenchange_event", "fullscreenchange")}} event to let it know that it's now in full screen mode. +- If permission is denied, the promise is rejected and the element receives a {{domxref("Element/fullscreenerror_event", "fullscreenerror")}} event instead. -## Usage notes +If the element has been detached from the original document, then the document receives these events instead. ### Compatible elements -An element that you wish to place into fullscreen mode has to meet a small number of -simple requirements: +An element that you wish to place into fullscreen mode has to meet a small number of simple requirements: -- It must be one of the standard HTML elements or {{SVGElement("svg")}} or - {{MathMLElement("math")}}. +- It must be one of the standard HTML elements or {{SVGElement("svg")}} or {{MathMLElement("math")}}. - It is _not_ a {{HTMLElement("dialog")}} element. -- It must either be located within the top-level document or in an - {{HTMLElement("iframe")}} which has the [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) - attribute applied to it. +- It must either be located within the top-level document or in an {{HTMLElement("iframe")}} which has the [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) attribute applied to it. -Additionally, any set Permissions Policies must allow the use of this feature. +Additionally, any set {{httpheader("Permissions-Policy")}} must allow the use of the `fullscreen` feature. ### Detecting fullscreen activation -You can determine whether or not your attempt to switch to fullscreen mode is -successful by using the {{jsxref("Promise")}} returned by -`requestFullscreen()`, as seen in the [examples](#examples) below. +You can determine whether or not your attempt to switch to fullscreen mode is successful by using the {{jsxref("Promise")}} returned by `requestFullscreen()`, as seen in the [examples](#examples) below. + +To learn when other code has toggled fullscreen mode on and off, you should establish listeners for the {{domxref("Document/fullscreenchange_event", "fullscreenchange")}} event on the {{domxref("Document")}}. +It's also important to listen for `fullscreenchange` to be aware when, for example, the user manually toggles fullscreen mode, or when the user switches applications, causing your application to temporarily exit fullscreen mode. + +### Keyboard locking + +Keyboard locking allows a fullscreen application to intercept and handle some keys and key combinations that would otherwise be exclusively handled by the browser or the underlying OS. +This can improve the user experience for games, for example, by allowing the Esc key to be used as a menu key instead of exiting fullscreen mode. +It can also be useful for applications such as remote desktop control, where you want almost all key events to be forwarded to the remote computer. + +The keyboard lock is activated by passing a keyboard lock mode value of `"browser"` to the [`options.keyboardLock`](#keyboardlock) parameter when activating fullscreen mode. +When keyboard lock is active in fullscreen mode the browser will redirect "many more" keyboard events to the application — the precise set of keys is browser dependent. +The web application should handle the event by first calling [`preventDefault()`](/en-US/docs/Web/API/Event/preventDefault) to cancel its default action. +Some key combinations are used for system control or have privacy risks, and hence cannot be intercepted and disabled using this mechanism (for example, Ctrl+Alt+Delete on Windows). + +Note that some browsers always disable the default action for the Esc key when in keyboard lock, so that pressing it doesn't automatically exit fullscreen mode. +However, as this is not guaranteed, you will still need to call `preventDefault()` to stop Esc key presses from exiting fullscreen mode. +More generally, you can't assume that the default action for any keyboard event is disabled by default. + +Browsers are expected to provide an alternative mechanism for exiting fullscreen mode when keyboard lock is enabled. +Most browsers use the Esc key to exit normal fullscreen mode, and a long-press Esc key to exit keyboard lock. +The keyboard lock is disabled when the browser exits fullscreen mode. + +### Security considerations + +[Transient user activation](/en-US/docs/Web/Security/Defenses/User_activation) is required. +The user has to interact with the page or a UI element in order for this feature to work. + +Fullscreen mode is controlled by the [Permissions-Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) directive {{HTTPHeader("Permissions-Policy/fullscreen","fullscreen")}}. + +The default allowlist for `screen-wake-lock` is `self`. +This allows fullscreen usage in same-origin nested frames but prevents them in third-party content. +Third party usage can be enabled by the server first setting the `Permissions-Policy` header to grant permission a particular third party origin. + +```http +Permissions-Policy: fullscreen=(self b.example.com) +``` + +Then the `allow="fullscreen"` attribute must be added to the frame container element for sources from that origin: + +```html + +``` -To learn when other code has toggled fullscreen mode on and off, you should establish -listeners for the {{domxref("Document/fullscreenchange_event", "fullscreenchange")}} event on the {{domxref("Document")}}. -It's also important to listen for `fullscreenchange` to be aware when, for -example, the user manually toggles fullscreen mode, or when the user switches -applications, causing your application to temporarily exit fullscreen mode. +The [Permissions API](/en-US/docs/Web/API/Permissions_API) `fullscreen` permission can be used to test whether access to use the mode is `granted`, `denied` or `prompt` (requires user acknowledgement of a prompt). ## Examples @@ -167,12 +207,92 @@ kbd { {{embedlivesample("requesting_fullscreen_mode", , "400", "", "", "", "fullscreen")}} +### Using keyboard lock + +This example is almost the same as the previous example, except that we request that fullscreen is opened with keyboard lock. + +#### JavaScript + +```js hidden +const video = document.querySelector("video"); +``` + +The modified key event listener code is shown below. + +The first difference is that we handle the event for the Esc key in fullscreen mode, calling `event.preventDefault()` to disable the default action (which would be to exit fullscreen mode). + +As before we call `requestFullscreen()` if Enter or Shift+F are pressed when not in fullscreen mode. +However in this case we pass the `keyboardLock` option with the value `"browser"`. + +```js +document.addEventListener("keydown", (event) => { + // Check if we're in fullscreen mode + if (document.fullscreenElement) { + // Cancel exiting via the Escape key + if (event.key === "Escape") { + event.preventDefault(); + // Do whatever else you might want to do when escape is pressed + } + } else { + // Open full screen if Enter or F is pressed. + // Note that "F" is case-sensitive (uppercase): + if (event.key === "Enter" || event.key === "F") { + // Otherwise enter fullscreen mode + video.requestFullscreen({ keyboardLock: "browser" }).catch((err) => { + console.error(`Error enabling fullscreen: ${err.message}`); + }); + } + } +}); +``` + +```html hidden +

+ The video element below shows a time-lapse of a flower blooming. You can + toggle fullscreen on and off using Enter or + Shift+F (uppercase "F"). The embedded document needs to have + + focus + + for the example to work. +

+ + +``` + +```css hidden +body { + font-family: + "Benton Sans", "Helvetica Neue", "Helvetica", "Arial", sans-serif; + margin: 2em; +} + +video::backdrop { + background-color: #444488; +} +button { + display: block; +} +kbd { + border: 2px solid #cdcdcd; + border-radius: 3px; + box-shadow: inset 0 -1px 0 0 #cdcdcd; + font-size: 0.825rem; + padding: 0.25rem; +} +``` + +#### Results + +Select the frame and press Shift+F. +When the page displays full frame, note the temporary notification at the top of the page that explains how to exit full screen mode. + +{{embedlivesample("Using keyboard lock", , "400", "", "", "", "fullscreen")}} + ### Using navigationUI -In this example, the entire document is placed into fullscreen mode by calling -`requestFullscreen()` on the document's -{{DOMxRef("Document.documentElement")}}, which is the document's root -{{HTMLElement("html")}} element. +In this example, the entire document is placed into fullscreen mode by calling `requestFullscreen()` on the document's {{DOMxRef("Document.documentElement")}}, which is the document's root {{HTMLElement("html")}} element. ```js let elem = document.documentElement; @@ -187,8 +307,7 @@ elem }); ``` -The promise's resolve handler does nothing, but if the promise is rejected, an error -message is displayed by calling {{DOMxRef("Window.alert", "alert()")}}. +The promise's resolve handler does nothing, but if the promise is rejected, an error message is displayed by calling {{DOMxRef("Window.alert", "alert()")}}. ### Using the screen option