New pages: htmloptionscollection

files/en-us/web/api/htmloptionscollection/add/index.md

@@ -0,0 +1,65 @@
+---
+title: "HTMLOptionsCollection: add() method"
+short-title: add()
+slug: Web/API/HTMLOptionsCollection/add
+page-type: web-api-instance-method
+browser-compat: api.HTMLOptionsCollection.add
+---
+
+{{APIRef("HTML DOM")}}
+
+The **`add()`** method of the {{DOMxRef("HTMLOptionsCollection")}} interface adds an {{domxref("HTMLOptionElement")}} or {{domxref("HTMLOptGroupElement")}} element to an `HTMLOptionsCollection`.
+
+By default, the `add()` appends the {{HTMLelement("option")}} or {{HTMLelement("optgroup")}} passed as the parameter to the end of the collection. You can define where the added `<option>` or `<optgroup>` should be placed by specifying the `before` parameter. The `before` is the `<option>` element or a numeric `0`-based index of the `<option>` element the added element should precede.
+
+If the `before` parameter is null or out of range (or omitted), the `<option>` or `<optgroup>` will be appended as the last element in the collection, outside of any {{HTMLelement("optgroup")}}. If the `<option>` referenced by the `before` parameter is in an {{HTMLelement("optgroup")}}, an added `HTMLOptionElement` will be in the same group.
+
+The `<optgroup>` element can only contain `<option>` elements as child nodes. The `add()` method will successfully add an `HTMLOptGroupElement` to the end of the `HTMLOptionsCollection` or between `<optgroup>` elements only. In other words, attempting to add an `HTMLOptGroupElement` before an `<option>` within an `<optgroup>` may silently if the `<option>` referenced by the `before` parameter is not the first `<option>` within its `<optgroup>`.
+
+## Syntax
+
+```js-nolint
+add(item)
+add(item, before)
+```
+
+### Parameters
+
+- `item`
+  - : An {{domxref("HTMLOptionElement")}} or {{domxref("HTMLOptGroupElement")}}.
+- `before` {{optional_inline}}
+  - : An element of the collection, or a numeric 0-based index representing the element the _item_ should be inserted before. If omitted, `null`, or the index does not exist, the new element is appended to the end of the collection.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+### Exceptions
+
+- `HierarchyRequestError` {{DOMxRef("DOMException")}}
+  - : Thrown if the _item_ passed to the method is an ancestor of the element into which it is to be inserted.
+
+## Examples
+
+```js
+const optionList = document.querySelector("select").options;
+const firstOption = document.createElement("option");
+firstOption.text = "new item";
+optionList.add(firstOption, 0); // added as the first item
+optionList.add(optionList[0]); // moves the first item to the end
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{HTMLElement("select")}}
+- {{DOMxRef("HTMLOptionsCollection.remove")}}
+- {{DOMxRef("HTMLOptionsCollection.length")}}
+- {{DOMxRef("HTMLOptionsCollection.selectedIndex")}}

files/en-us/web/api/htmloptionscollection/index.md

@@ -13,13 +13,20 @@ The **`HTMLOptionsCollection`** interface represents a collection of [`<option>`
 
 ## Instance properties
 
-- `length`
-  - : `unsigned long`. As optionally allowed by the spec, this property isn't read-only. You can either remove options from the end by lowering the value, or add blank options at the end by raising the value. Mozilla allows this, while other implementations could potentially throw a [DOMException](/en-US/docs/Web/API/DOMException).
+- {{domxref("HTMLOptionsCollection.length")}}
+  - : Returns or sets the number of options in the collection.
+- {{domxref("HTMLOptionsCollection.selectedIndex")}}
+  - : The index number of the first selected {{HTMLElement("option")}} element. The value `-1` indicates no element is selected.
 
 ## Instance methods
 
 _This interface inherits the methods of its parent, [`HTMLCollection`](/en-US/docs/Web/API/HTMLCollection)._
 
+- {{domxref("HTMLOptionsCollection.add()")}}
+  - : Appends an {{domxref("HTMLOptionElement")}} or {{domxref("HTMLOptGroupElement")}} element to the collection of `option` elements or adds it before a specified option.
+- {{domxref("HTMLOptionsCollection.remove()")}}
+  - : Removes the element at the specified index from the options collection.
+
 ## Specifications
 
 {{Specifications}}
@@ -32,4 +39,6 @@ _This interface inherits the methods of its parent, [`HTMLCollection`](/en-US/do
 
 - {{DOMxRef("HTMLOptionElement")}}
 - {{DOMxRef("HTMLCollection")}}
+- {{DOMxRef("HTMLOptGroupElement")}}
+- {{DOMxRef("HTMLSelectElement")}}
 - [Indexed collections guide](/en-US/docs/Web/JavaScript/Guide/Indexed_collections)

files/en-us/web/api/htmloptionscollection/length/index.md

@@ -0,0 +1,43 @@
+---
+title: "HTMLOptionsCollection: length property"
+short-title: length
+slug: Web/API/HTMLOptionsCollection/length
+page-type: web-api-instance-property
+browser-compat: api.HTMLOptionsCollection.length
+---
+
+{{APIRef("DOM")}}
+
+The **`length`** property of the {{DOMxRef("HTMLOptionsCollection")}} interface returns the number of {{htmlelement("option")}} elements in the collection. The property can get or set the size of the collection.
+
+When setting `length`, property value assignment will truncate the `<option>` elements in the `<select>` if the value is smaller than the current `length` and will add new blank `<option>` elements to the `<select>` if the value is greater than the current `length`.
+
+## Value
+
+An integer value representing the number of items in this `HTMLOptionsCollection`.
+
+## Example
+
+```js
+const optCollection = document.getElementById("fruits").options;
+const origLength = optCollection.length;
+optCollection.length += 50; // adds 50 blank options to the collection
+optCollection.length = origLength; // truncates the list back to the original size
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{DOMxRef("HTMLOptionsCollection.add()")}}
+- {{DOMxRef("HTMLOptionsCollection.remove()")}}
+- {{DOMxRef("HTMLOptionsCollection.selectedIndex")}}
+- {{domxref("HTMLSelectElement") }}
+- {{domxref("HTMLOptGroupElement")}}
+- {{domxref("HTMLCollection.length")}}

files/en-us/web/api/htmloptionscollection/remove/index.md

@@ -0,0 +1,52 @@
+---
+title: "HTMLOptionsCollection: remove() method"
+short-title: remove()
+slug: Web/API/HTMLOptionsCollection/remove
+page-type: web-api-instance-method
+browser-compat: api.HTMLOptionsCollection.remove
+---
+
+{{ APIRef("HTML DOM") }}
+
+The **`remove()`** method of the {{DOMxRef("HTMLOptionsCollection")}} interface removes the {{HTMLelement("option")}} element specified by the index from the ancestor {HTMLelement("select")}} element.
+
+## Syntax
+
+```js-nolint
+remove(index)
+```
+
+### Parameters
+
+- `index`
+  - : A zero-based integer for the index of the {{ domxref("HTMLOptionElement") }} in the {{DOMxRef("HTMLOptionsCollection")}}. If the index is not found the method has no effect.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+## Examples
+
+```js
+const optionList = document.querySelector("select").options;
+const listLength = optionList.length;
+optionList.remove(length - 1); // removes the last item
+optionList.remove(optionList[0]); // removes the first item
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{DOMxRef("HTMLOptionsCollection.add")}}
+- {{DOMxRef("HTMLOptionsCollection.length")}}
+- {{DOMxRef("HTMLOptionsCollection.selectedIndex")}}
+- {{domxref("HTMLOptionsCollection") }}
+- {{domxref("HTMLOptionsCollection.remove()")}}
+- {{domxref("Element.remove")}}

files/en-us/web/api/htmloptionscollection/selectedindex/index.md

@@ -0,0 +1,43 @@
+---
+title: "HTMLOptionsCollection: selectedIndex property"
+short-title: selectedIndex
+slug: Web/API/HTMLOptionsCollection/selectedIndex
+page-type: web-api-instance-property
+browser-compat: api.HTMLOptionsCollection.selectedIndex
+---
+
+{{APIRef("HTML DOM")}}
+
+The **`selectedIndex`** property of the {{DOMxRef("HTMLOptionsCollection")}} interface is the numeric index of the first selected
+{{HTMLElement("option")}} element, if any, or −1 if no `<option>` is selected. The property changes which option element is selected, or selects an option element if none is selected, with the `-1` deselecting any currently selected elements
+
+## Value
+
+A number.
+
+## Examples
+
+```js
+const optionColl = document.getElementById("select").options;
+console.log(`selected option: ${optionColl.selectedIndex}`); // the index of the first selected option, or -1 if no option is selected
+optionColl.selectedIndex = 0; // selects the first item
+optionColl.selectedIndex = -1; // deselects any selected option
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{DOMxRef("HTMLOptionsCollection.length")}}
+- {{DOMxRef("HTMLOptionsCollection.add()")}}
+- {{DOMxRef("HTMLOptionsCollection.remove()")}}
+- {{DOMxRef("HTMLOptionsCollection")}}
+- {{DOMxRef("HTMLOptionElement")}}
+- {{DOMxRef("HTMLOptGroupElement")}}
+- {{DOMxRef("HTMLSelectElement")}}