From 48c95eaa06ea0d5e6c0e6b37d4930398f2e2ac15 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Tue, 21 Apr 2026 16:23:26 +1000 Subject: [PATCH 1/7] FF151 Element.requestFullScreen() option.keyboardLock docs --- .../api/element/requestfullscreen/index.md | 129 +++++++++++------- 1 file changed, 80 insertions(+), 49 deletions(-) diff --git a/files/en-us/web/api/element/requestfullscreen/index.md b/files/en-us/web/api/element/requestfullscreen/index.md index c2d113eccf721a9..5c133ea322f1057 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,117 @@ 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. + The browser disables the default action for some keys, such as exiting fullscreen mode when the Esc key is pressed. + Applications can call [`preventDefault()`](/en-US/docs/Web/API/Event/preventDefault) on events to cancel other default actions. - `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. -[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. +The method requires permission. -## Usage notes +- 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. ### 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 Permissions-Policies 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 some keys and key combinations that would otherwise be handled by the browser or the underlying OS. +This can improve the user experience for applications such as games, allowing you to use key combinations that would otherwise cause the browser to exit fullscreen mode, or otherwise affect the application and operating system. +For example, this mechanism allows the Esc key to be used as a menu key in games, instead of exiting fullscreen mode. + +The keyboard lock is activated by passing a keyboard lock mode value, other than `none`, to the [`options.keyboardLock`](#keyboardlock) parameter when activating fullscreen mode. +When keyboard lock is active in fullscreen mode the browser will redirect keyboard events that would otherwise trigger system or browser behavior to the application. +The browser may remove the action associated with the events, or the web application can prevent the default action by calling [`preventDefault()`](/en-US/docs/Web/API/Event/preventDefault) on the event. +Note that the key combinations that are used for system control or that have privacy risks cannot be disabled using this mechanism. + +Browsers are expected to provide an alternative for exiting fullscreen mode when keyboard lock is enabled, since the Esc default action is disabled. +On Firefox this is a long-press of the Esc key. + +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 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 @@ -187,8 +219,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 From 385956da757bcc748b5ebd9091b17b86ee0db64f Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Tue, 21 Apr 2026 18:11:05 +1000 Subject: [PATCH 2/7] Add keyboardLock example --- .../api/element/requestfullscreen/index.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/files/en-us/web/api/element/requestfullscreen/index.md b/files/en-us/web/api/element/requestfullscreen/index.md index 5c133ea322f1057..59706e69728bbc9 100644 --- a/files/en-us/web/api/element/requestfullscreen/index.md +++ b/files/en-us/web/api/element/requestfullscreen/index.md @@ -199,6 +199,84 @@ kbd { {{embedlivesample("requesting_fullscreen_mode", , "400", "", "", "", "fullscreen")}} +### Using keyboard lock + +This example is _exactly_ the same as the last one except that it specifies the `keyboardLock` option when requesting requests fullscreen. +On supporting browsers, this disables the default Esc key action to leave fullscreen mode, and enables long-press for the same action. + +#### JavaScript + +```js hidden +const video = document.querySelector("video"); + +document.addEventListener("keydown", (event) => { + // Note that "F" is case-sensitive (uppercase): + if (event.key === "Enter" || event.key === "F") { + // Check if we're in fullscreen mode + if (document.fullscreenElement) { + document.exitFullscreen(); + return; + } +``` + +The code that sets the keyboard lock mode to `"browser"` is: + +```js + // Otherwise enter fullscreen mode + video.requestFullscreen({ keyboardLock: "browser" }).catch((err) => { + console.error(`Error enabling fullscreen: ${err.message}`); + }); + } +``` + +```js hidden +}); +``` + +```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 that the temporary notification at the top of the page: "Exit full screen (Press and hold Esc)". + +{{embedlivesample("Using keyboard lock", , "400", "", "", "", "fullscreen")}} + ### Using navigationUI In this example, the entire document is placed into fullscreen mode by calling From 54480f628772e68adbd2da06eb04f2d9f524efa8 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 24 Apr 2026 17:15:21 +1000 Subject: [PATCH 3/7] Tidy keyboard lock --- .../api/element/requestfullscreen/index.md | 80 +++++++++++-------- 1 file changed, 46 insertions(+), 34 deletions(-) diff --git a/files/en-us/web/api/element/requestfullscreen/index.md b/files/en-us/web/api/element/requestfullscreen/index.md index 59706e69728bbc9..c4b959a7c5bf774 100644 --- a/files/en-us/web/api/element/requestfullscreen/index.md +++ b/files/en-us/web/api/element/requestfullscreen/index.md @@ -30,8 +30,13 @@ requestFullscreen(options) - `"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. - The browser disables the default action for some keys, such as exiting fullscreen mode when the Esc key is pressed. - Applications can call [`preventDefault()`](/en-US/docs/Web/API/Event/preventDefault) on events to cancel other default actions. + Applications should intercept evens 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. @@ -84,7 +89,7 @@ An element that you wish to place into fullscreen mode has to meet a small numbe - 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. -Additionally, any set Permissions-Policies must allow the use of the `fullscreen` feature. +Additionally, any set {{httpheader("Permissions-Policy")}} must allow the use of the `fullscreen` feature. ### Detecting fullscreen activation @@ -95,18 +100,21 @@ It's also important to listen for `fullscreenchange` to be aware when, for examp ### Keyboard locking -Keyboard locking allows a fullscreen application to intercept some keys and key combinations that would otherwise be handled by the browser or the underlying OS. -This can improve the user experience for applications such as games, allowing you to use key combinations that would otherwise cause the browser to exit fullscreen mode, or otherwise affect the application and operating system. +Keyboard locking allows a fullscreen application to intercept 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 applications such as games, allowing you to intercept key combinations that would otherwise not reach your code or have have unintended side effects outside the control of your application. For example, this mechanism allows the Esc key to be used as a menu key in games, instead of exiting fullscreen mode. The keyboard lock is activated by passing a keyboard lock mode value, other than `none`, to the [`options.keyboardLock`](#keyboardlock) parameter when activating fullscreen mode. -When keyboard lock is active in fullscreen mode the browser will redirect keyboard events that would otherwise trigger system or browser behavior to the application. -The browser may remove the action associated with the events, or the web application can prevent the default action by calling [`preventDefault()`](/en-US/docs/Web/API/Event/preventDefault) on the event. -Note that the key combinations that are used for system control or that have privacy risks cannot be disabled using this mechanism. +When keyboard lock is active in fullscreen mode the browser will redirect almost all keyboard events to the application, including those that would otherwise trigger system or browser behavior. +The web application should then prevent the default action by calling [`preventDefault()`](/en-US/docs/Web/API/Event/preventDefault) on the event. +Some key combinations are used for system control or have privacy risks, and hence cannot be disabled using this mechanism (for example, Ctrl+Alt+Delete on Windows). -Browsers are expected to provide an alternative for exiting fullscreen mode when keyboard lock is enabled, since the Esc default action is disabled. -On Firefox this is a long-press of the Esc key. +Note that the default actions for some keyboard events may be disabled by default in fullscreen mode in some Browsers. +However this is not guaranteed, so generally you will need to call `preventDefault()` to disable the default action for all events that interest you. +In particular, this includes the event for the Esc key, which may otherwise exit you out of fullscreen mode even if you have keyboard lock! +Browsers are expected to provide an alternative mechanism for exiting fullscreen mode when keyboard lock is enabled, since the normal default action is disabled. +Most browsers use the Esc 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 @@ -201,35 +209,41 @@ kbd { ### Using keyboard lock -This example is _exactly_ the same as the last one except that it specifies the `keyboardLock` option when requesting requests fullscreen. -On supporting browsers, this disables the default Esc key action to leave fullscreen mode, and enables long-press for the same action. +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"); - -document.addEventListener("keydown", (event) => { - // Note that "F" is case-sensitive (uppercase): - if (event.key === "Enter" || event.key === "F") { - // Check if we're in fullscreen mode - if (document.fullscreenElement) { - document.exitFullscreen(); - return; - } ``` -The code that sets the keyboard lock mode to `"browser"` is: +The modified key event listener code is shown below. + +The first difference is that we call `event.preventDefault()` to disable the default action in fullscreen mode, which exits the mode when the Esc key is pressed. +While we might not need to do this on some browsers, which disable the default action for the normal fullscreen exit key by default, this can't be guaranteed on all browsers. + +As before we call `requestFullscreen()` if Enter or Shift+F are pressed when not in fullscreen mode. +The difference here is that we specify the `keyboardLock` option. ```js - // Otherwise enter fullscreen mode - video.requestFullscreen({ keyboardLock: "browser" }).catch((err) => { - console.error(`Error enabling fullscreen: ${err.message}`); - }); +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}`); + }); + } } -``` - -```js hidden }); ``` @@ -273,16 +287,14 @@ kbd { #### Results Select the frame and press Shift + F. -When the page displays full frame, note that the temporary notification at the top of the page: "Exit full screen (Press and hold Esc)". +When the page displays full frame, note the temporary notification at the top of the page that explains how to exit full screen mode. +On Firefox this says "Exit full screen (Press and hold Esc)". {{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; From 7370f847da9f501bddedd4ef0e1fc19bc228dcb9 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Mon, 27 Apr 2026 15:42:51 +1000 Subject: [PATCH 4/7] tidy keyboard locking section --- .../api/element/requestfullscreen/index.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/files/en-us/web/api/element/requestfullscreen/index.md b/files/en-us/web/api/element/requestfullscreen/index.md index c4b959a7c5bf774..0b354499cf4c27d 100644 --- a/files/en-us/web/api/element/requestfullscreen/index.md +++ b/files/en-us/web/api/element/requestfullscreen/index.md @@ -100,20 +100,20 @@ It's also important to listen for `fullscreenchange` to be aware when, for examp ### Keyboard locking -Keyboard locking allows a fullscreen application to intercept 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 applications such as games, allowing you to intercept key combinations that would otherwise not reach your code or have have unintended side effects outside the control of your application. -For example, this mechanism allows the Esc key to be used as a menu key in games, instead of exiting fullscreen mode. +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, other than `none`, to the [`options.keyboardLock`](#keyboardlock) parameter when activating fullscreen mode. -When keyboard lock is active in fullscreen mode the browser will redirect almost all keyboard events to the application, including those that would otherwise trigger system or browser behavior. +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 then prevent the default action by calling [`preventDefault()`](/en-US/docs/Web/API/Event/preventDefault) on the event. Some key combinations are used for system control or have privacy risks, and hence cannot be disabled using this mechanism (for example, Ctrl+Alt+Delete on Windows). -Note that the default actions for some keyboard events may be disabled by default in fullscreen mode in some Browsers. -However this is not guaranteed, so generally you will need to call `preventDefault()` to disable the default action for all events that interest you. -In particular, this includes the event for the Esc key, which may otherwise exit you out of fullscreen mode even if you have keyboard lock! +Note that some browsers disable the default action for the Esc key, which would otherwise exit the element from fullscreen mode even if you have keyboard lock! +However this is not guaranteed, so generally you will need to call `preventDefault()` to disable the action if you don't want the key to exit the mode. +More generally, you can't assume that the default action is disabled by default. -Browsers are expected to provide an alternative mechanism for exiting fullscreen mode when keyboard lock is enabled, since the normal default action is disabled. +Browsers are expected to provide an alternative mechanism for exiting fullscreen mode when keyboard lock is enabled. Most browsers use the Esc 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. @@ -209,7 +209,7 @@ kbd { ### Using keyboard lock -This example is almost the same as the previous example except that we request that fullscreen is opened with keyboard lock. +This example is almost the same as the previous example, except that we request that fullscreen is opened with keyboard lock. #### JavaScript From ed6dff25ee0a700be714fb591db4e3e96c1563d5 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Mon, 27 Apr 2026 15:58:44 +1000 Subject: [PATCH 5/7] Tweaks --- .../api/element/requestfullscreen/index.md | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/files/en-us/web/api/element/requestfullscreen/index.md b/files/en-us/web/api/element/requestfullscreen/index.md index 0b354499cf4c27d..b99762392834d6d 100644 --- a/files/en-us/web/api/element/requestfullscreen/index.md +++ b/files/en-us/web/api/element/requestfullscreen/index.md @@ -30,7 +30,7 @@ requestFullscreen(options) - `"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 evens 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. + 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. @@ -106,15 +106,15 @@ It can also be useful for applications such as remote desktop control, where you 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 then prevent the default action by calling [`preventDefault()`](/en-US/docs/Web/API/Event/preventDefault) on the event. -Some key combinations are used for system control or have privacy risks, and hence cannot be disabled using this mechanism (for example, Ctrl+Alt+Delete on Windows). +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 disable the default action for the Esc key, which would otherwise exit the element from fullscreen mode even if you have keyboard lock! -However this is not guaranteed, so generally you will need to call `preventDefault()` to disable the action if you don't want the key to exit the mode. -More generally, you can't assume that the default action is disabled by default. +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 to exit normal fullscreen mode, and a long-press Esc key to exit keyboard lock. +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 @@ -132,7 +132,7 @@ Third party usage can be enabled by the server first setting the `Permissions-Po Permissions-Policy: fullscreen=(self b.example.com) ``` -Then the `allow="fullscreen"` attribute must be added the frame container element for sources from that origin: +Then the `allow="fullscreen"` attribute must be added to the frame container element for sources from that origin: ```html @@ -219,11 +219,10 @@ const video = document.querySelector("video"); The modified key event listener code is shown below. -The first difference is that we call `event.preventDefault()` to disable the default action in fullscreen mode, which exits the mode when the Esc key is pressed. -While we might not need to do this on some browsers, which disable the default action for the normal fullscreen exit key by default, this can't be guaranteed on all browsers. +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. -The difference here is that we specify the `keyboardLock` option. +However in this case we pass the `keyboardLock` option with the value `"browser"`. ```js document.addEventListener("keydown", (event) => { From 39c2307ec5a21a2eb37d0c55e2567288061a751a Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 8 May 2026 09:58:48 +1000 Subject: [PATCH 6/7] Accept all suggestions from code review Co-authored-by: Vadim Makeev --- files/en-us/web/api/element/requestfullscreen/index.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/files/en-us/web/api/element/requestfullscreen/index.md b/files/en-us/web/api/element/requestfullscreen/index.md index b99762392834d6d..82025661334ca00 100644 --- a/files/en-us/web/api/element/requestfullscreen/index.md +++ b/files/en-us/web/api/element/requestfullscreen/index.md @@ -249,8 +249,8 @@ document.addEventListener("keydown", (event) => { ```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 + toggle fullscreen on and off using Enter or Shift+F (uppercase "F"). + The embedded document needs to have focus @@ -285,9 +285,8 @@ kbd { #### Results -Select the frame and press Shift + F. +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. -On Firefox this says "Exit full screen (Press and hold Esc)". {{embedlivesample("Using keyboard lock", , "400", "", "", "", "fullscreen")}} From e6403ad5cfeda8adb99a89f1dc8d6a341a96abe0 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 8 May 2026 10:01:10 +1000 Subject: [PATCH 7/7] Update files/en-us/web/api/element/requestfullscreen/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/en-us/web/api/element/requestfullscreen/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/web/api/element/requestfullscreen/index.md b/files/en-us/web/api/element/requestfullscreen/index.md index 82025661334ca00..46d29b30b3f8328 100644 --- a/files/en-us/web/api/element/requestfullscreen/index.md +++ b/files/en-us/web/api/element/requestfullscreen/index.md @@ -249,8 +249,8 @@ document.addEventListener("keydown", (event) => { ```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 + toggle fullscreen on and off using Enter or + Shift+F (uppercase "F"). The embedded document needs to have focus