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 <[email protected]>
mdn · Dec 8, 2023 · e312e15 · e312e15
1 parent 2b65309
commit e312e15
Show file tree

Hide file tree

Showing 4 changed files with 114 additions and 2 deletions.
diff --git 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
@@ -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
@@ -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 `<select>` element with two options.
+
+#### HTML
+
+```html
+<p>
+  <select>
+    <option value="1">One</option>
+    <option value="2">Two</option>
+  </select>
+  <button type="button">Show Picker</button>
+</p>
+```
+
+#### JavaScript
+
+The code gets the `<button>` and adds a listener for its `click` event.
+The event handler gets the `<select>` element and calls `showPicker()` on it.
+
+```js
+const button = document.querySelector("button");
+button.addEventListener("click", (event) => {
+  const select = event.srcElement.previousElementSibling;
+  try {
+    select.showPicker();
+  } catch (error) {
+    window.alert(error);
+  }
+});
+```
+
+<!-- A live example cannot be shown here because they run in a cross-origin frame, and would cause a SecurityError -->
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{ HTMLElement("select") }}
+- {{ domxref("HTMLSelectElement") }}
+- {{ domxref("HTMLInputElement.showPicker()") }}
diff --git a/files/en-us/web/security/user_activation/index.md b/files/en-us/web/security/user_activation/index.md
@@ -38,6 +38,7 @@ APIs that require transient activation (list is not exhaustive):
 - {{domxref("GPUAdapter.requestAdapterInfo()")}}
 - {{domxref("HID.requestDevice()")}}
 - {{domxref("HTMLInputElement.showPicker()")}}
+- {{domxref("HTMLSelectElement.showPicker()")}}
 - {{domxref("HTMLVideoElement.requestPictureInPicture()")}}
 - {{domxref("IdleDetector/requestPermission_static", "IdleDetector.requestPermission()")}}
 - {{domxref("MediaDevices.selectAudioOutput()")}}
@@ -50,12 +51,12 @@ APIs that require transient activation (list is not exhaustive):
 - {{domxref("RemotePlayback.prompt()")}}
 - {{domxref("USB.requestDevice()")}}
 - {{domxref("Keyboard.lock()")}}
+- {{domxref("Window.getScreenDetails()")}}
 - {{domxref("Window.open()")}}
+- {{domxref("Window.queryLocalFonts()")}}
 - {{domxref("Window.showOpenFilePicker()")}}
 - {{domxref("Window.showSaveFilePicker()")}}
 - {{domxref("Window.showDirectoryPicker()")}}
-- `Window.getScreenDetails()`
-- {{domxref("Window.queryLocalFonts()")}}
 - {{domxref("XRSystem.requestSession()")}}
 
 ## Sticky activation