25.173. Input: an input element in an HTML form DOM Level 2 HTML: Node  Element HTMLElement Input 25.173.1. Properties
String accept When type is "file", this property is a comma-separated list of MIME types that specify the types of files that may be uploaded. Mirrors the accept attribute.
String accessKey The keyboard shortcut (which must be a single character) a browser can use to transfer keyboard focus to this input element. Mirrors the accesskey attribute.
deprecated String align The vertical alignment of this element with respect to the surrounding text, or the left or right float for the element. Mirrors the align attribute.
String alt Alternate text to be displayed by browsers that cannot render this input element. Particularly useful when type is "image". Mirrors the alt attribute.
boolean checked When type is "radio" or "checkbox", this property specifies whether the element is "checked" or not. Setting this property changes the visual appearance of the input element. Mirrors the checked attribute.
boolean defaultChecked When type is "radio" or "checkbox", this property holds the initial value of the checked attribute as it appears in the document source. When the form is reset, the checked property is restored to the value of this property. Changing the value of this property changes the value of the checked property and the current checked state of the element.
String defaultValue When type is "text", "password", or "file", this property holds the initial value displayed by the element. When the form is reset, the element is restored to this value. Changing the value of this property also changes the value property and the currently displayed value.
boolean disabled If true, the input element is disabled and is unavailable for user input. Mirrors the disabled attribute.
readonly HTMLFormElement form The Form object representing the <form> element that contains this input element, or null if the input element is not within a form.
long maxLength If type is "text" or "password", this property specifies the maximum number of characters that the user is allowed to enter. Note that this is not the same as the size property. Mirrors the maxlength attribute.
String name The name of the input element, as specified by the name attribute. See the following Description section for further details on form element names.
boolean readOnly If true and type is "text" or "password", the user is not allowed to enter text into the element. Mirrors the readonly attribute.
unsigned long size If type is "text" or "password", this property specifies the width of the element in characters. Mirrors the size attribute. See also maxLength.
String src For input elements with a type of "image", specifies the URL of the image to be displayed. Mirrors the src attribute.
long tabIndex The position of this input element in the tabbing order. Mirrors the tabindex attribute.
String type The type of the input element. Mirrors the type attribute. See the Description section for further details on form element types.
String useMap For elements with a type of "image", this property specifies the name of a <map>element that provides a client-side image map for the element.
String value The value that is passed to the web server when the form is submitted. For elements with a type of "text", "password", or "file", this property is the editable text contained by the input element. For elements with a type of "button", "submit", or "reset", this is the (noneditable) label that appears in the button. For security reasons, the value property of FileUpload elements may be read-only. Similarly, the value returned by this property for Password elements may not contain the user's actual input. 25.173.2. Methods
blur( ) Takes keyboard focus away from the element.
click( ) If type is "button", "checkbox", "radio", "reset", or "submit", this method simulates a mouse-click on the element.
focus( ) Transfers keyboard focus to this input element.
select( ) If type is "file", "password", or "text", this method selects the text displayed by the element. In many browsers, this means that when the user next enters a character, the selected text is deleted and replaced with the newly typed character. 25.173.3. Event Handlers
onblur Invoked when the user takes keyboard focus away from the element.
onchange For text-entry elements, this event handler is invoked when the user changes the displayed text and then "commits" those changes by tabbing or clicking to transfer keyboard focus to another element. This handler does not report keystroke-by-keystroke edits. Toggle button elements of type "checkbox" and "radio" may also fire this event (in addition to the onclick event) when the user toggles them.
onclick For push button and toggle button elements, this event handler is invoked when the user activates the button with a mouse click or by keyboard traversal.
onfocus Invoked when the user gives keyboard focus to the element. 25.173.4. Description An Input object represents an HTML <input> tag that defines a scriptable form input element. The three most important properties of an Input object are type, value, and name. These properties are described in the subsections that follow. See Chapter 18 for more information about HTML forms and form elements. 25.173.4.1. Input element types The type attribute of the HTML <input> tag specifies the kind of input element that is to be created. This attribute is available to client-side JavaScript as the type property of the Input object and is useful to determine the type of an unknown form element, for example, when iterating through the elements[] array of a Form object. The legal values of type are the following:
"button" The input element is a graphical push button that displays the plain text specified by the value property. The button has no default behavior and must be given an onclick event handler in order to be useful. For buttons that submit or reset a form, use a type of "submit" or "reset". Note that the HTML <button> tag can create buttons that display arbitrary HTML instead of plain text.
"checkbox" An input element of this type displays a toggle button that the user can check and uncheck. The checked property holds the current state of the button, and the onclick event handler is triggered whenever this value changes (browsers may also trigger the onchange handler). The value property is an internal value for submission to a web server and is not displayed to the user. To associate a label with a checkbox, simply place the label text near the <input> tag, optionally using a <label> tag. Checkbox elements often appear in groups, and the members of a group are sometimes given the same name property and different value properties, for the convenience of the web server to which the form is submitted.
"file" This type creates a "file upload" element. This element consists of a text input field for entering the name of a file, along with a button that opens a file-selection dialog box for graphical selection of a file. The value property holds the name of the file the user has specified, but when a form containing a file-upload element is submitted, the browser sends the contents of the selected file to the server instead of just sending the filename. (For this to work, the form must use "multipart/form-data" encoding and the POST method.) For security, the file-upload element does not allow HTML authors or JavaScript programmers to specify a default filename. The HTML value attribute is ignored, and the value property is read-only for this type of element, which means that only the user may enter a filename. When the user selects or edits a filename, a file-upload element triggers the onchange event handler.
"hidden" An input element of this type is, in fact, hidden. The value property of this invisible form element holds an arbitrary string to be submitted to the web server. Use an element of this type if you want to submit data that the user did not input directly.
"image" This type of input element is a form submit button that displays an image (specified by the src property) instead of displaying a textual label. The value property is unused. See the element type "submit" for further details.
"password" This text input field is intended for input of sensitive data, such as passwords. As the user types, her input is masked (with asterisks, for example) to prevent bystanders from reading the input value over her shoulder. Note, however that the user's input is not encrypted in any way: when the form is submitted, it is sent in clear text. As a security precaution, some browsers may prevent JavaScript code from reading the value property. In other respects, a password input element behaves like an element of type "text". It triggers the onchange event handler when the user changes the displayed value.
"radio" An input element of this type displays a single graphical radio button. A radio button is a button in a group of buttons that represents a set of mutually exclusive choices. When one button is selected, the previously selected button is deselected (as in the mechanical station preset buttons of old car radios). In order for a group of radio buttons to exhibit this mutually exclusive behavior, they must appear in the same <form> and must have the same name. For toggle buttons without mutual exclusion, use a type of "checkbox". Note that the HTML <select> tag can also be used for presenting exclusive or nonexclusive choices (see Select). The checked property indicates whether a radio button is selected. There is no way to determine which button in a mutually exclusive group of radio buttons is selected: you must examine the checked property of each one. Radio buttons trigger the onclick event handler when selected or deselected. The value property specifies a value to be submitted to a web server and is not displayed within the form. To specify a label for a radio button, do so externally to the <input> tag, such as with a <label> tag.
"reset" An input element of this type is like a push button created with type "button" but has a more specialized purpose. When a reset button element is clicked, the values of all input elements in the form that contains it are reset to their default values (specified by the HTML value attribute or the JavaScript defaultValue property). The value property specifies the text to appear in the button. A reset button triggers the onclick handler before resetting the form, and this handler may cancel the reset by returning false or by using other event cancellation methods described in Chapter 17. See also the Form.reset( ) method and the Form.onreset event handler.
"submit" An element of this type is a push button that submits the containing <form> when clicked. The value property specifies the text to appear in the button. The onclick event handler is triggered before the form is submitted, and a handler may cancel form submission by returning false. See also the Form.submit( ) method and Form.onsubmit event handler.
"text" This is the default value of the type property; it creates a single-line text input field. The HTML value attribute specifies the default text to appear in the field, and the JavaScript value property holds the currently displayed text. The onchange event handler is triggered when the user edits the displayed text and then transfers input focus to some other element. Use size to specify the width of the input field and maxLength to specify the maximum number of characters that may be entered. When a form contains only a single input element of type "text", pressing Enter submits the form. For multiline text input, use the HTML <textarea> tag (see Textarea). For masked text input, set type to "password". 25.173.4.2. Input element values The value property of the Input object is a read/write string property that specifies the text that is sent to the web server when the form that contains the input element is submitted. Depending on the value of the type property, the value property may also hold user-visible text. For input elements of type "text" and "file", this property holds whatever text the user has entered. For elements of type "button", "reset", and "submit", the value property specifies the text that appears in the button. For other element types, such as "checkbox", "radio", and "image", the contents of the value property are not displayed to the user and are used only for form submission purposes. 25.173.4.3. Input element names The name property of the Input object is a String that provides a name for the input element. Its value comes from the HTML name attribute. The name of a form element is used for two purposes. First, it is used when the form is submitted. Data for each element in the form is usually submitted in the format: name=value
where name and value are encoded as necessary for transmission. If a name is not specified for a form element, the data for that element cannot be submitted to a web server. The second use of the name property is to refer to a form element in JavaScript code. The name of an element becomes a property of the form that contains the element. The value of this property is a reference to the element. For example, if address is a form that contains a text input element with the name zip, address.zip refers to that text input element. For input elements of type "radio" and "checkbox", it is common to define more than one related object, each of which have the same name property. In this case, data is submitted to the server with this format: name=value1,value2,...,valuen
Similarly, in JavaScript, each element that shares a name becomes an element of an array with that name. Thus, if four Checkbox objects in the form order share the name options, they are available in JavaScript as elements of the array order.options[]. 25.173.4.4. Related form elements The HTML <input> tag allows you to create a number of different form elements. But <button>, <select>, and <textarea> tags also create form elements. 25.173.5. See Also Form, Form.elements[], Option, Select, Textarea; Chapter 18 |
