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
|
---
title: HTMLSelectElement
slug: Web/API/HTMLSelectElement
tags:
- API
- HTML DOM
- HTMLSelectElement
- Interface
- NeedsTranslation
- Reference
- TopicStub
translation_of: Web/API/HTMLSelectElement
---
<div>{{APIRef("HTML DOM")}}</div>
<p>The <code><strong>HTMLSelectElement</strong></code> interface represents a {{HTMLElement("select")}} HTML Element. These elements also share all of the properties and methods of other HTML elements via the {{domxref("HTMLElement")}} interface.</p>
<p>{{InheritanceDiagram(600, 120)}}</p>
<h2 id="Properties">Properties</h2>
<p><em>This interface inherits the properties of {{domxref("HTMLElement")}}, and of {{domxref("Element")}} and {{domxref("Node")}}.</em></p>
<dl>
<dt>{{domxref("HTMLSelectElement.autofocus")}}</dt>
<dd>A {{jsxref("Boolean")}} reflecting the {{htmlattrxref("autofocus", "select")}} HTML attribute, which indicates whether the control should have input focus when the page loads, unless the user overrides it, for example by typing in a different control. Only one form-associated element in a document can have this attribute specified. {{gecko_minversion_inline("2.0")}}</dd>
<dt>{{domxref("HTMLSelectElement.disabled")}}</dt>
<dd>A {{jsxref("Boolean")}} reflecting the {{htmlattrxref("disabled", "select")}} HTML attribute, which indicates whether the control is disabled. If it is disabled, it does not accept clicks.</dd>
<dt>{{domxref("HTMLSelectElement.form")}}{{ReadOnlyInline}}</dt>
<dd>An {{domxref("HTMLFormElement")}} referencing the form that this element is associated with. If the element is not associated with of a {{HTMLElement("form")}} element, then it returns <code>null</code>.</dd>
<dt>{{domxref("HTMLSelectElement.labels")}}{{ReadOnlyInline}}</dt>
<dd>A {{domxref("NodeList")}} of {{HTMLElement("label")}} elements associated with the element.</dd>
<dt>{{domxref("HTMLSelectElement.length")}}</dt>
<dd>An <code>unsigned long</code> The number of {{HTMLElement("option")}} elements in this <code>select</code> element.</dd>
<dt>{{domxref("HTMLSelectElement.multiple")}}</dt>
<dd>A {{jsxref("Boolean")}} reflecting the {{htmlattrxref("multiple", "select")}} HTML attribute, which indicates whether multiple items can be selected.</dd>
<dt>{{domxref("HTMLSelectElement.name")}}</dt>
<dd>A {{domxref("DOMString")}} reflecting the {{htmlattrxref("name", "select")}} HTML attribute, containing the name of this control used by servers and DOM search functions.</dd>
<dt>{{domxref("HTMLSelectElement.options")}}{{ReadOnlyInline}}</dt>
<dd>An {{domxref("HTMLOptionsCollection")}} representing the set of {{HTMLElement("option")}} ({{domxref("HTMLOptionElement")}}) elements contained by this element.</dd>
<dt>{{domxref("HTMLSelectElement.required")}}</dt>
<dd>A {{jsxref("Boolean")}} reflecting the {{htmlattrxref("required", "select")}} HTML attribute, which indicates whether the user is required to select a value before submitting the form. {{gecko_minversion_inline("2.0")}}</dd>
<dt>{{domxref("HTMLSelectElement.selectedIndex")}}</dt>
<dd>A <code>long</code> reflecting the index of the first selected {{HTMLElement("option")}} element. The value <code>-1</code> indicates no element is selected.</dd>
<dt>{{domxref("HTMLSelectElement.selectedOptions")}}{{ReadOnlyInline}}</dt>
<dd>An {{domxref("HTMLCollection")}} representing the set of {{HTMLElement("option")}} elements that are selected.</dd>
<dt>{{domxref("HTMLSelectElement.size")}}</dt>
<dd>A <code>long</code> reflecting the {{htmlattrxref("size", "select")}} HTML attribute, which contains the number of visible items in the control. The default is 1, unless <code>multiple</code> is <code>true</code>, in which case it is 4.</dd>
<dt>{{domxref("HTMLSelectElement.type")}}{{ReadOnlyInline}}</dt>
<dd>A {{domxref("DOMString")}} represeting the form control's type. When <code>multiple</code> is <code>true</code>, it returns <code>"select-multiple"</code>; otherwise, it returns <code>"select-one"</code>.</dd>
<dt>{{domxref("HTMLSelectElement.validationMessage")}}{{ReadOnlyInline}}</dt>
<dd>A {{domxref("DOMString")}} representing a localized message that describes the validation constraints that the control does not satisfy (if any). This attribute is the empty string if the control is not a candidate for constraint validation (<code>willValidate</code> is false), or it satisfies its constraints.</dd>
<dt>{{domxref("HTMLSelectElement.validity")}}{{ReadOnlyInline}}</dt>
<dd>A {{domxref("ValidityState")}} reflecting the validity state that this control is in.</dd>
<dt>{{domxref("HTMLSelectElement.value")}}</dt>
<dd>A {{domxref("DOMString")}} reflecting the value of the form control. Returns the <code>value</code> property of the first selected option element if there is one, otherwise the empty string.</dd>
<dt>{{domxref("HTMLSelectElement.willValidate")}}{{ReadOnlyInline}}</dt>
<dd>A {{jsxref("Boolean")}} that indicates whether the button is a candidate for constraint validation. It is <code>false</code> if any conditions bar it from constraint validation.</dd>
</dl>
<h2 id="Methods">Methods</h2>
<p><em>This interface inherits the methods of {{domxref("HTMLElement")}}, and of {{domxref("Element")}} and {{domxref("Node")}}.</em></p>
<dl>
<dt>{{domxref("HTMLSelectElement.add()")}}</dt>
<dd>Adds an element to the collection of <code>option</code> elements for this <code>select</code> element.</dd>
<dt>{{domxref("HTMLSelectElement.blur()")}}{{obsolete_inline}}</dt>
<dd>Removes input focus from this element. <em>This method is now implemented on {{domxref("HTMLElement")}}</em>.</dd>
<dt>{{domxref("HTMLSelectElement.checkValidity()")}}</dt>
<dd>Checks whether the element has any constraints and whether it satisfies them. If the element fails its constraints, the browser fires a cancelable {{domxref("HTMLInputElement/invalid_event", "invalid")}} event at the element (and returns <code>false</code>).</dd>
<dt>{{domxref("HTMLSelectElement.focus()")}}{{obsolete_inline}}</dt>
<dd>Gives input focus to this element. <em>This method is now implemented on {{domxref("HTMLElement")}}</em>.</dd>
<dt>{{domxref("HTMLSelectElement.item()")}}</dt>
<dd>Gets an item from the options collection for this {{HTMLElement("select")}} element. You can also access an item by specifying the index in array-style brackets or parentheses, without calling this method explicitly.</dd>
<dt>{{domxref("HTMLSelectElement.namedItem()")}}</dt>
<dd>Gets the item in the options collection with the specified name. The name string can match either the <code>id</code> or the <code>name</code> attribute of an option node. You can also access an item by specifying the name in array-style brackets or parentheses, without calling this method explicitly.</dd>
<dt>{{domxref("HTMLSelectElement.remove()")}}</dt>
<dd>Removes the element at the specified index from the options collection for this <code>select</code> element.</dd>
<dt>{{domxref("HTMLSelectElement.reportValidity()")}}</dt>
<dd>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 <code>false</code>; if there are no problems, it returns <code>true</code>.</dd>
<dt>{{domxref("HTMLSelectElement.setCustomValidity()")}}</dt>
<dd>Sets the custom validity message for the selection element to the specified message. Use the empty string to indicate that the element does <em>not</em> have a custom validity error.</dd>
</dl>
<h2 id="Events">Events</h2>
<p>Listen to these events using {{domxref("EventTarget/addEventListener", "addEventListener()")}} or by assigning an event listener to the <code>on<em>eventname</em></code> property of this interface:</p>
<dl>
<dt>{{domxref("HTMLElement/input_event", "input")}} event</dt>
<dd>Fires when the <code>value</code> of an {{HTMLElement("input")}}, {{HTMLElement("select")}}, or {{HTMLElement("textarea")}} element has been changed.</dd>
</dl>
<h2 id="Example">Example</h2>
<h3 id="Get_information_about_the_selected_option">Get information about the selected option</h3>
<pre class="brush: js">/* assuming we have the following HTML
<select id='s'>
<option>First</option>
<option selected>Second</option>
<option>Third</option>
</select>
*/
var select = document.getElementById('s');
// return the index of the selected option
console.log(select.selectedIndex); // 1
// return the value of the selected option
console.log(select.options[select.selectedIndex].value) // Second
</pre>
<p>A better way to track changes to the user's selection is to watch for the {{domxref("HTMLElement/change_event", "change")}} event to occur on the <code><select></code>. This will tell you when the value changes, and you can then update anything you need to. See <a href="/en-US/docs/Web/API/HTMLElement/change_event#<select>_element">the example provided</a> in the documentation for the <code>change</code> event for details.</p>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
<thead>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{SpecName('HTML WHATWG', '#htmlselectelement', 'HTMLSelectElement')}}</td>
<td>{{Spec2('HTML WHATWG')}}</td>
<td>Since the latest snapshot, {{SpecName('HTML5 W3C')}}, it adds the <code>autocomplete</code> property and the <code>reportValidity()</code> method.</td>
</tr>
<tr>
<td>{{SpecName('HTML5 W3C', 'forms.html#htmlselectelement', 'HTMLSelectElement')}}</td>
<td>{{Spec2('HTML5 W3C')}}</td>
<td>Is a snapshot of {{SpecName("HTML WHATWG")}}.<br>
It adds the <code>autofocus</code>, <code>form</code>, <code>required</code>, <code>labels</code>, <code>selectedOptions</code>, <code>willValidate</code>, <code>validity</code> and <code>validationMessage</code> properties.<br>
The <code>tabindex</code> property and the <code>blur()</code> and <code>focus()</code> methods have been moved to {{domxref("HTMLElement")}}.<br>
The methods <code>item()</code>, <code>namedItem()</code>, <code>checkValidity()</code> and <code>setCustomValidity()</code>.</td>
</tr>
<tr>
<td>{{SpecName('DOM2 HTML', 'html.html#ID-94282980', 'HTMLSelectElement')}}</td>
<td>{{Spec2('DOM2 HTML')}}</td>
<td><code>options</code> now returns an {{domxref("HTMLOptionsCollection")}}.<br>
<code>length</code> now returns an <code>unsigned long</code>.</td>
</tr>
<tr>
<td>{{SpecName('DOM1', 'level-one-html.html#ID-94282980', 'HTMLSelectElement')}}</td>
<td>{{Spec2('DOM1')}}</td>
<td>Initial definition</td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{Compat("api.HTMLSelectElement")}}</p>
<h2 id="See_also">See also</h2>
<ul>
<li>The {{HTMLElement("select")}} HTML element, which implements this interface.</li>
</ul>
|
