input element APIsvalue [ = value ]Returns the current value of the form control.
Can be set, to change the value.
Throws an InvalidStateError exception if it is
set to any value other than the empty string when the control is a
file upload control.
checked [ = value ]Returns the current checkedness of the form control.
Can be set, to change the checkedness.
filesReturns a FileList object listing the selected files of
the form control.
Returns null if the control isn't a file control.
valueAsDate [ = value ]Returns a Date object representing the form
control's value, if
applicable; otherwise, returns null.
Can be set, to change the value.
Throws an InvalidStateError exception if the
control isn't date- or time-based.
valueAsNumber [ = value ]Returns a number representing the form control's value, if applicable; otherwise, returns NaN.
Can be set, to change the value.
Throws an InvalidStateError exception if the
control is neither date- or time-based nor numeric.
stepUp( [ n ] )stepDown( [ n ] )Changes the form control's value by the value given in the
step attribute, multiplied by
n. The default value for n
is 1.
Throws InvalidStateError exception if the control
is neither date- or time-based nor numeric, if the step attribute's value is "any", if the current value could not be parsed, or if
stepping in the given direction by the given amount would take the
value out of range.
listReturns the datalist element indicated by the
list attribute.
The value IDL
attribute allows scripts to manipulate the value of an input
element. The attribute is in one of the following modes, which
define its behavior:
On getting, it must return the current value of the element. On setting,
it must set the element's value to the new value, set the
element's dirty value
flag to true, invoke the value sanitization
algorithm, if the element's type attribute's current state
defines one, and then, if the element has a text entry cursor
position, should move the text entry cursor position to the end of
the text field, unselecting any selected text and resetting the
selection direction to none.
On getting, if the element has a value attribute, it must return
that attribute's value; otherwise, it must return the empty
string. On setting, it must set the element's value attribute to the new
value.
On getting, if the element has a value attribute, it must return
that attribute's value; otherwise, it must return the string
"on". On setting, it must set the element's
value attribute to the new
value.
On getting, it must return the string "C:\fakepath\" followed by the filename of the
first file in the list of selected files, if
any, or the empty string if the list is empty. On setting, if the
new value is the empty string, it must empty the list of selected files;
otherwise, it must throw an InvalidStateError
exception.
This "fakepath" requirement is a sad accident of history. See the example in the File Upload state section for more information.
The checked IDL
attribute allows scripts to manipulate the checkedness of an
input element. On getting, it must return the current
checkedness of the element;
and on setting, it must set the element's checkedness to the new value and
set the element's dirty checkedness
flag to true.
The files IDL
attribute allows scripts to access the element's selected files. On
getting, if the IDL attribute applies, it must return a
FileList object that represents the current selected files. The
same object must be returned until the list of selected files
changes. If the IDL attribute does not apply, then it must instead
return null. [FILEAPI]
The valueAsDate IDL
attribute represents the value of the element, interpreted
as a date.
On getting, if the valueAsDate attribute does not
apply, as defined for the input element's type attribute's current state, then
return null. Otherwise, run the algorithm to convert a
string to a Date object defined for that state;
if the algorithm returned a Date object, then return
it, otherwise, return null.
On setting, if the valueAsDate attribute does not
apply, as defined for the input element's type attribute's current state, then
throw an InvalidStateError exception; otherwise, if the
new value is null or a Date object representing the NaN
time value, then set the value
of the element to the empty string; otherwise, run the algorithm to convert a
Date object to a string, as defined for that
state, on the new value, and set the value of the element to resulting
string.
The valueAsNumber IDL
attribute represents the value
of the element, interpreted as a number.
On getting, if the valueAsNumber attribute does
not apply, as defined for the input element's type attribute's current state, then
return a Not-a-Number (NaN) value. Otherwise, if the valueAsDate
attribute applies, run the algorithm to convert a
string to a Date object defined for that state;
if the algorithm returned a Date object, then return
the time value of the object (the number of milliseconds from
midnight UTC the morning of 1970-01-01 to the time represented by
the Date object), otherwise, return a Not-a-Number
(NaN) value. Otherwise, run the algorithm to convert a
string to a number defined for that state; if the algorithm
returned a number, then return it, otherwise, return a Not-a-Number
(NaN) value.
On setting, if the valueAsNumber attribute does
not apply, as defined for the input element's type attribute's current state, then
throw an InvalidStateError exception. Otherwise, if
the valueAsDate
attribute applies, run the algorithm to convert a
Date object to a string defined for that state,
passing it a Date object whose time value is the
new value, and set the value
of the element to resulting string. Otherwise, run the algorithm to convert a
number to a string, as defined for that state, on the new
value, and set the value of
the element to resulting string.
The stepDown(n) and stepUp(n) methods, when invoked, must run the
following algorithm:
If the stepDown() and
stepUp() methods do not
apply, as defined for the input element's type attribute's current state, then
throw an InvalidStateError exception, and abort these
steps.
If the element has no allowed value step, then throw an
InvalidStateError exception, and abort these
steps.
If applying the algorithm to convert a
string to a number to the string given by the element's
value results in an error,
then throw an InvalidStateError exception, and abort
these steps; otherwise, let value be the result
of that algorithm.
Let n be the argument, or 1 if the argument was omitted.
Let delta be the allowed value step multiplied by n.
If the method invoked was the stepDown() method, negate delta.
Let value be the result of adding delta to value.
If the element has a minimum, and the value is less than that minimum, then throw a
InvalidStateError exception.
If the element has a maximum, and the value is greater than that maximum, then throw a
InvalidStateError exception.
Let value as string be the result of
running the algorithm to convert a
number to a string, as defined for the input
element's type attribute's
current state, on value.
Set the value of the element to value as string.
The list IDL
attribute must return the current suggestions source element, if
any, or null otherwise.
When the input
event applies, any time the user causes the element's value to change, the user agent must
queue a task to fire a simple event that
bubbles named input at the
input element. User agents may wait for a suitable
break in the user's interaction before queuing the task; for
example, a user agent could wait for the user to have not hit a key
for 100ms, so as to only fire the event when the user pauses,
instead of continuously for each keystroke.
Examples of a user changing the element's value would include the user typing into a text field, pasting a new value into the field, or undoing an edit in that field. Some user interactions do not cause changes to the value, e.g. hitting the "delete" key in an empty text field, or replacing some text in the field with text from the clipboard that happens to be exactly the same text.
When the change event applies,
if the element does not have an activation behavior
defined but uses a user interface that involves an explicit commit
action, then any time the user commits a change to the element's
value or list of selected files, the
user agent must queue a task to fire a simple
event that bubbles named change at the input
element.
An example of a user interface with a commit action would be a File Upload control that consists of a single button that brings up a file selection dialog: when the dialog is closed, if that the file selection changed as a result, then the user has committed a new file selection.
Another example of a user interface with a commit action would be a Date control that allows both text-based user input and user selection from a drop-down calendar: while text input might not have an explicit commit step, selecting a date from the drop down calendar and then dismissing the drop down would be a commit action.
When the user agent changes the element's value on behalf of the user (e.g. as part of a form prefilling feature), the user agent must follow these steps:
input event
applies, queue a task to fire a simple
event that bubbles named input at the input
element.change event
applies, queue a task to fire a simple
event that bubbles named change at the input
element.In addition, when the change event applies, change events can also be fired as part
of the element's activation behavior and as part of the
unfocusing steps.
The task source for these tasks is the user interaction task source.