From e312e1548dda157699cff0fe339532a617477652 Mon Sep 17 00:00:00 2001 From: Luke Warlow Date: Fri, 8 Dec 2023 00:48:29 +0000 Subject: [PATCH] Add page for HTMLSelectElement showPicker() (#29406) * Add page for HTMLSelectElement showPicker() * Minor subedit * Update files/en-us/web/api/htmlselectelement/showpicker/index.md * Update files/en-us/web/api/htmlselectelement/showpicker/index.md * Add usage example code * Subedit and cross link --------- Co-authored-by: Hamish Willee --- .../api/htmlinputelement/showpicker/index.md | 1 + .../en-us/web/api/htmlselectelement/index.md | 2 + .../api/htmlselectelement/showpicker/index.md | 108 ++++++++++++++++++ .../web/security/user_activation/index.md | 5 +- 4 files changed, 114 insertions(+), 2 deletions(-) create mode 100644 files/en-us/web/api/htmlselectelement/showpicker/index.md diff --git a/files/en-us/web/api/htmlinputelement/showpicker/index.md b/files/en-us/web/api/htmlinputelement/showpicker/index.md index 8f28e458ea73e41..e542871a02c27d0 100644 --- a/files/en-us/web/api/htmlinputelement/showpicker/index.md +++ b/files/en-us/web/api/htmlinputelement/showpicker/index.md @@ -171,5 +171,6 @@ button.addEventListener("click", () => { - {{ HTMLElement("input") }} - {{ domxref("HTMLInputElement") }} +- {{ domxref("HTMLSelectElement.showPicker()") }} - {{htmlelement("datalist")}} - [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) diff --git a/files/en-us/web/api/htmlselectelement/index.md b/files/en-us/web/api/htmlselectelement/index.md index b6114f632830f1f..5a61ee5e591af3b 100644 --- a/files/en-us/web/api/htmlselectelement/index.md +++ b/files/en-us/web/api/htmlselectelement/index.md @@ -72,6 +72,8 @@ _This interface inherits the methods of {{domxref("HTMLElement")}}, and of {{dom - : This method reports the problems with the constraints on the element, if any, to the user. If there are problems, it fires a cancelable {{domxref("HTMLInputElement/invalid_event", "invalid")}} event at the element, and returns `false`; if there are no problems, it returns `true`. - {{domxref("HTMLSelectElement.setCustomValidity()")}} - : Sets the custom validity message for the selection element to the specified message. Use the empty string to indicate that the element does _not_ have a custom validity error. +- {{domxref("HTMLSelectElement.showPicker()", "showPicker()")}} {{experimental_inline}} + - : Shows the option picker. ## Events diff --git a/files/en-us/web/api/htmlselectelement/showpicker/index.md b/files/en-us/web/api/htmlselectelement/showpicker/index.md new file mode 100644 index 000000000000000..b1fadf39bd2b86a --- /dev/null +++ b/files/en-us/web/api/htmlselectelement/showpicker/index.md @@ -0,0 +1,108 @@ +--- +title: "HTMLSelectElement: showPicker() method" +short-title: showPicker() +slug: Web/API/HTMLSelectElement/showPicker +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.HTMLSelectElement.showPicker +--- + +{{ APIRef("HTML DOM") }} {{SeeCompatTable}} + +The **`HTMLSelectElement.showPicker()`** method displays the browser picker for a `select` element. + +This is the same picker that would normally be displayed when the element is selected, but can be triggered from a button press or other user interaction. + +## Syntax + +```js-nolint +showPicker() +``` + +### Parameters + +None. + +### Return value + +None ({{jsxref("undefined")}}). + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the element is not mutable, meaning that the user cannot modify it and/or that it cannot be automatically prefilled. +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if not explicitly triggered by a user action such as a touch gesture or mouse click (the picker requires {{Glossary("Transient activation")}}). +- `NotSupportedError` {{domxref("DOMException")}} + - : Thrown if the element associated with the picker is not being rendered. +- `SecurityError` {{domxref("DOMException")}} + - : Thrown if called in a cross-origin iframe. + +## Security considerations + +[Transient user activation](/en-US/docs/Web/Security/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 is only allowed to be called in same-origin iframes; an exception is thrown if this is called in a cross-origin iframe. + +## Examples + +### Feature detection + +The code below shows how to check if `showPicker()` is supported: + +```js +if ("showPicker" in HTMLSelectElement.prototype) { + // showPicker() is supported. +} +``` + +### Launching the picker + +This example shows how to use a button to launch the picker for a ` + + + + +

+``` + +#### JavaScript + +The code gets the `