Section 25.253. Select: a graphical selection list

25.253. Select: a graphical selection list

DOM Level 2 HTML: Node Element HTMLElement Select

25.253.1. Properties

readonly Form form

The <form> element that contains this <select> element.

readonly long length

The number of <option> elements contained by this <select> element. Same as options.length.

readonly HTMLCollection options

An array (HTMLCollection) of Option objects that represent the <option> elements contained in this <select> element, in the order in which they appear. See Select.options[] for further details.

long selectedIndex

The position of the selected option in the options array. If no options are selected, this property is -1. If multiple options are selected, this property holds the index of the first selected option.

Setting the value of this property selects the specified option and deselects all other options, even if the Select object has the multiple attribute specified. When you're doing listbox selection (when size > 1), you can deselect all options by setting selectedIndex to -1. Note that changing the selection in this way does not trigger the onchange( ) event handler.

readonly String type

If multiple is true, this property is "select-multiple"; otherwise, it is "select-one". This property exists for compatibilty with the type property of the Input object.

In addition to the properties above, Select objects also mirror HTML attributes with the following properties:

Property	Attribute	Description
boolean disabled	disabled	Whether the user element is disabled
boolean multiple	multiple	Whether more than one option may be selected
String name	name	Element name for form submission
long size	size	The number of options to display at once
long tabIndex	tabindex	Position of Select element in the tabbing order

25.253.2. Methods

add( )

Inserts a new Option object into the options array, either by appending it at the end of the array or by inserting it before another specified option.

blur( )

Takes keyboard focus away from this element.

focus( )

Transfers keyboard focus to this element.

remove( )

Removes the <option> element at the specified position.

25.253.3. Event Handlers

onchange

Invoked when the user selects or deselects an item.

25.253.4. HTML Syntax

A Select element is created with a standard HTML <select> tag. Options to appear within the Select element are created with the <option> tag:

 <form>        ... <select    name="name"  // A name that identifies this element; specifies name property     [ size="integer" ]      // Number of visible options in Select element     [ multiple ]            // Multiple options may be selected, if present     [ onchange="handler" ]  // Invoked when the selection changes > <option value="value1" [selected]>option_label1 <option value="value2" [selected]>option_label2// Other options here </select>    ... </form> 

25.253.5. Description

The Select element represents an HTML <select> tag, which displays a graphical list of choices to the user. If the multiple attribute is present in the HTML definition of the element, the user may select any number of options from the list. If that attribute is not present, the user may select only one option, and options have a radio-button behaviorselecting one deselects whichever was previously selected.

The options in a Select element may be displayed in two distinct ways. If the size attribute has a value greater than 1, or if the multiple attribute is present, they are displayed in a list box that is size lines high in the browser window. If size is smaller than the number of options, the listbox includes a scrollbar so all the options are accessible. On the other hand, if size is specified as 1 and multiple is not specified, the currently selected option is displayed on a single line, and the list of other options is made available through a drop-down menu. The first presentation style displays the options clearly but requires more space in the browser window. The second style requires minimal space but does not display alternative options as explicitly.

The options[] property of the Select element is the most interesting. This is the array of Option objects that describe the choices presented by the Select element. The length property specifies the length of this array (as does options.length). See Option for details.

For a Select element without the multiple attribute specified, you can determine which option is selected with the selectedIndex property. When multiple selections are allowed, however, this property tells you the index of only the first selected option. To determine the full set of selected options, you must iterate through the options[] array and check the selected property of each Option object.

The options displayed by the Select element may be dynamically modified. Add a new option with the add( ) method and the Option( ) constructor; remove an option with the remove( ) method. Changes are also possible by direct manipulation of the options array.

25.253.6. See Also

Form, Option, Select.options[]; Chapter 18