Repository navigation
Expand file tree
/
Copy pathindex.md
More file actions
179 lines (126 loc) · 5.07 KB
/
Copy pathindex.md
File metadata and controls
179 lines (126 loc) · 5.07 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
---
title: "HTMLInputElement: showPicker() method"
short-title: showPicker()
slug: Web/API/HTMLInputElement/showPicker
page-type: web-api-instance-method
browser-compat: api.HTMLInputElement.showPicker
---
{{ APIRef("HTML DOM") }}
The **`HTMLInputElement.showPicker()`** method displays the browser picker for an `input` 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.
Commonly browsers implement it for inputs of these types: `"date"`, `"month"`, `"week"`, `"time"`, `"datetime-local"`, `"color"`, or `"file"`.
It can also be prepopulated with items from a {{htmlelement("datalist")}} element or [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) attribute.
More generally, this method should ideally display the picker for any input element on the platform that has a picker.
## 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")}}).
- `SecurityError` {{domxref("DOMException")}}
- : Thrown if called in a cross-origin iframe, except for file and color pickers (exempt for historical reasons).
## Security
[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.
## Examples
### Feature Detection
The code below shows how to check if `showPicker()` is supported:
```js
if ("showPicker" in HTMLInputElement.prototype) {
// showPicker() is supported.
}
```
### Normal input pickers
This example shows how this feature can be used for `color` and `file` input pickers.
> [!NOTE]
> Pickers for `date`, `datetime-local`, `month`, `time`, `week` are launched in the same way.
> They cannot be shown here because live examples run in a cross-origin frame, and would cause a [`SecurityError`](#securityerror)
#### HTML
```html
<p>
<input type="color" />
<button id="color">Show the color picker</button>
</p>
<p>
<input type="file" />
<button id="file">Show the file picker</button>
</p>
```
#### JavaScript
The code simply gets the previous element of the selected button and calls `showPicker()` on it.
```js
document.querySelectorAll("button").forEach((button) => {
button.addEventListener("click", (event) => {
const input = event.srcElement.previousElementSibling;
try {
input.showPicker();
} catch (error) {
console.log(error);
}
});
});
```
#### Result
Click the button next to each input type to show its picker.
{{EmbedLiveSample("Normal input pickers", "100%", "140px")}}
### showPicker() for a datalist input
`showPicker()` can launch the picker for a list of options defined in a [`<datalist>`](/en-US/docs/Web/HTML/Reference/Elements/datalist).
First we define a `<datalist>` in HTML consisting of a number of internet browsers, an input of type `text` that uses it, and a button.
```html
<datalist id="browsers">
<option value="Chrome"></option>
<option value="Firefox"></option>
<option value="Opera"></option>
<option value="Safari"></option>
<option value="Microsoft Edge"></option>
</datalist>
<input type="text" list="browsers" />
<button>Select browser</button>
```
The code below adds an event listener that calls `showPicker()` when the button is clicked.
```js
const button = document.querySelector("button");
const browserInput = document.querySelector("input");
button.addEventListener("click", () => {
try {
browserInput.showPicker();
} catch (error) {
// Fall back to another picker mechanism
}
});
```
As for the other pickers, we can't show this code running as a live example because it runs in a cross-origin frame, and would cause a [`SecurityError`](#securityerror).
### showPicker() for autocomplete
`showPicker()` can launch a picker for an [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) input.
Here we define an input that takes an autocomplete option of "name".
```html
<input autocomplete="name" /> <button>Show autocomplete options</button>
```
The code below shows the picker for the input when the button is clicked.
```js
const button = document.querySelector("button");
const browserInput = document.querySelector("input");
button.addEventListener("click", () => {
try {
browserInput.showPicker();
} catch (error) {
// Fall back to another picker mechanism
}
});
```
## Specifications
{{Specifications}}
## Browser compatibility
{{Compat}}
## See also
- {{ HTMLElement("input") }}
- {{ domxref("HTMLInputElement") }}
- {{ domxref("HTMLSelectElement.showPicker()") }}
- {{htmlelement("datalist")}}
- [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete)