input elementStatus: Last call for comments
type attribute is not in the Hidden state: Interactive content.acceptaltautocompleteautofocuscheckeddisabledformformactionformenctypeformmethodformnovalidateformtargetheightlistmaxmaxlengthminmultiplenamepatternplaceholderreadonlyrequiredsizesrcsteptypevaluewidthinterface HTMLInputElement : HTMLElement {
attribute DOMString accept;
attribute DOMString alt;
attribute DOMString autocomplete;
attribute boolean autofocus;
attribute boolean defaultChecked;
attribute boolean checked;
attribute boolean disabled;
readonly attribute HTMLFormElement form;
readonly attribute FileList files;
attribute DOMString formAction;
attribute DOMString formEnctype;
attribute DOMString formMethod;
attribute boolean formNoValidate;
attribute DOMString formTarget;
attribute DOMString height;
attribute boolean indeterminate;
readonly attribute HTMLElement list;
attribute DOMString max;
attribute long maxLength;
attribute DOMString min;
attribute boolean multiple;
attribute DOMString name;
attribute DOMString pattern;
attribute DOMString placeholder;
attribute boolean readOnly;
attribute boolean required;
attribute unsigned long size;
attribute DOMString src;
attribute DOMString step;
attribute DOMString type;
attribute DOMString defaultValue;
attribute DOMString value;
attribute Date valueAsDate;
attribute double valueAsNumber;
readonly attribute HTMLOptionElement selectedOption;
attribute DOMString width;
void stepUp(in optional long n);
void stepDown(in optional long n);
readonly attribute boolean willValidate;
readonly attribute ValidityState validity;
readonly attribute DOMString validationMessage;
boolean checkValidity();
void setCustomValidity(in DOMString error);
readonly attribute NodeList labels;
void select();
attribute unsigned long selectionStart;
attribute unsigned long selectionEnd;
void setSelectionRange(in unsigned long start, in unsigned long end);
};
The input element represents a typed data field,
usually with a form control to allow the user to edit the data.
The type
attribute controls the data type (and associated control) of the
element. It is an enumerated attribute. The following
table lists the keywords and states for the attribute — the
keywords in the left column map to the states in the cell in the
second column on the same row as the keyword.
| Keyword | State | Data type | Control type |
|---|---|---|---|
hidden
| Hidden | An arbitrary string | n/a |
text
| Text | Text with no line breaks | Text field |
search
| Search | Text with no line breaks | Search field |
tel
| Telephone | Text with no line breaks | A text field |
url
| URL | An absolute IRI | A text field |
email
| An e-mail address or list of e-mail addresses | A text field | |
password
| Password | Text with no line breaks (sensitive information) | Text field that obscures data entry |
datetime
| Date and Time | A date and time (year, month, day, hour, minute, second, fraction of a second) with the time zone set to UTC | A date and time control |
date
| Date | A date (year, month, day) with no time zone | A date control |
month
| Month | A date consisting of a year and a month with no time zone | A month control |
week
| Week | A date consisting of a week-year number and a week number with no time zone | A week control |
time
| Time | A time (hour, minute, seconds, fractional seconds) with no time zone | A time control |
datetime-local
| Local Date and Time | A date and time (year, month, day, hour, minute, second, fraction of a second) with no time zone | A date and time control |
number
| Number | A numerical value | A text field or spinner control |
range
| Range | A numerical value, with the extra semantic that the exact value is not important | A slider control or similar |
color
| Color | An sRGB color with 8-bit red, green, and blue components | A color well |
checkbox
| Checkbox | A set of zero or more values from a predefined list | A checkbox |
radio
| Radio Button | An enumerated value | A radio button |
file
| File Upload | Zero or more files each with a MIME type and optionally a file name | A label and a button |
submit
| Submit Button | An enumerated value, with the extra semantic that it must be the last value selected and initiates form submission | A button |
image
| Image Button | A coordinate, relative to a particular image's size, with the extra semantic that it must be the last value selected and initiates form submission | Either a clickable image, or a button |
reset
| Reset Button | n/a | A button |
button
| Button | n/a | A button |
The missing value default is the Text state.
Which of the accept, alt, autocomplete, checked, formaction, formenctype, formmethod, formnovalidate, formtarget, height, list, max, maxlength, min, multiple, pattern, placeholder, readonly, required, size, src, step, and width content attributes, the checked, files, valueAsDate, valueAsNumber, list, and selectedOption IDL
attributes, the select() method, the selectionStart and
selectionEnd
IDL attributes, the setSelectionRange()
method, the stepUp() and
stepDown() methods, and the
input and change events apply to an
input element depends on the state of its type attribute. The following table
is non-normative and summarizes which of
those content attributes, IDL attributes, methods, and events apply
to each state:
| Hidden | Text, Search, URL, Telephone | Password | Date and Time, Date, Month, Week, Time | Local Date and Time, Number | Range | Color | Checkbox, Radio Button | File Upload | Submit Button | Image Button | Reset Button, Button | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Content attributes | |||||||||||||
accept
| · | · | · | · | · | · | · | · | · | Yes | · | · | · |
alt
| · | · | · | · | · | · | · | · | · | · | · | Yes | · |
autocomplete
| · | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | · | · | · |
checked
| · | · | · | · | · | · | · | · | Yes | · | · | · | · |
formaction
| · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
formenctype
| · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
formmethod
| · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
formnovalidate
| · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
formtarget
| · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
height
| · | · | · | · | · | · | · | · | · | · | · | Yes | · |
list
| · | Yes | Yes | · | Yes | Yes | Yes | Yes | · | · | · | · | · |
max
| · | · | · | · | Yes | Yes | Yes | · | · | · | · | · | · |
maxlength
| · | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · |
min
| · | · | · | · | Yes | Yes | Yes | · | · | · | · | · | · |
multiple
| · | · | Yes | · | · | · | · | · | · | Yes | · | · | · |
pattern
| · | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · |
placeholder
| · | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · |
readonly
| · | Yes | Yes | Yes | Yes | Yes | · | · | · | · | · | · | · |
required
| · | Yes | Yes | Yes | Yes | Yes | · | · | Yes | Yes | · | · | · |
size
| · | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · |
src
| · | · | · | · | · | · | · | · | · | · | · | Yes | · |
step
| · | · | · | · | Yes | Yes | Yes | · | · | · | · | · | · |
width
| · | · | · | · | · | · | · | · | · | · | · | Yes | · |
| IDL attributes and methods | |||||||||||||
checked
| · | · | · | · | · | · | · | · | Yes | · | · | · | · |
files
| · | · | · | · | · | · | · | · | · | Yes | · | · | · |
value
| default | value | value | value | value | value | value | value | default/on | filename | default | default | default |
valueAsDate
| · | · | · | · | Yes | · | · | · | · | · | · | · | · |
valueAsNumber
| · | · | · | · | Yes | Yes | Yes | · | · | · | · | · | · |
list
| · | Yes | Yes | · | Yes | Yes | Yes | Yes | · | · | · | · | · |
selectedOption
| · | Yes | Yes | · | Yes | Yes | Yes | Yes | · | · | · | · | · |
select()
| · | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · |
selectionStart
| · | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · |
selectionEnd
| · | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · |
setSelectionRange()
| · | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · |
stepDown()
| · | · | · | · | Yes | Yes | Yes | · | · | · | · | · | · |
stepUp()
| · | · | · | · | Yes | Yes | Yes | · | · | · | · | · | · |
| Events | |||||||||||||
input event
| · | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | · | · | · |
change event
| · | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | · |
When an input element's type attribute changes state, and
when the element is first created, the element's rendering and
behavior must change to the new state's accordingly and the
value sanitization algorithm, if one is defined for the
type attribute's new state,
must be invoked.
Each input element has a value, which is exposed by the value IDL attribute. Some states
define an algorithm
to convert a string to a number, an algorithm to convert a
number to a string, an algorithm to convert a
string to a Date object, and an algorithm to convert a
Date object to a string, which are used by
max,
min,
step,
valueAsDate,
valueAsNumber,
stepDown(), and
stepUp().
Each input element has a boolean dirty value flag. When
it is true, the element is said to have a dirty value. The
dirty value flag
must be initially set to false when the element is created, and must
be set to true whenever the user interacts with the control in a way
that changes the value.
The value
content attribute gives the default value of the input
element. When the value content attribute is added,
set, or removed, if the control does not have a dirty value, the user agent
must set the value of the
element to the value of the value content attribute, if there is
one, or the empty string otherwise, and then run the current
value sanitization algorithm, if one is
defined.
Each input element has a checkedness, which is exposed by
the checked IDL
attribute.
Each input element has a boolean dirty checkedness
flag. When it is true, the element is said to have a dirty
checkedness. The dirty checkedness
flag must be initially set to false when the element is
created, and must be set to true whenever the user interacts with
the control in a way that changes the checkedness.
The checked
content attribute is a boolean attribute that gives the
default checkedness of the
input element. When the checked content attribute is
added, if the control does not have dirty checkedness, the user
agent must set the checkedness of the element to
true; when the checked
content attribute is removed, if the control does not have dirty checkedness, the user
agent must set the checkedness of the element to
false.
The reset
algorithm for input elements is to set the dirty value flag and
dirty checkedness
flag back to false, set the value of the element to the value of
the value content attribute,
if there is one, or the empty string otherwise, set the checkedness of the element to true
if the element has a checked
content attribute and false if it does not, and then invoke the
value sanitization algorithm, if the type attribute's current state
defines one.
Each input element is either mutable or immutable. Except where
otherwise specified, an input element is always mutable. Similarly, except where
otherwise specified, the user agent should not allow the user to
modify the element's value or
checkedness.
When an input element is disabled, it is immutable.
When an input element does not have a
Document node as one of its ancestors (i.e. when it is
not in the document), it is immutable.
The readonly attribute can also in
some cases (e.g. for the Date state, but not the Checkbox state) make an
input element immutable.
When an input element is cloned, the element's value, dirty value flag,
checkedness, and dirty checkedness
flag must be propagated to the clone when it is created.
The form attribute is used to
explicitly associate the input element with its
form owner. The name
attribute represents the element's name. The disabled attribute is used to make
the control non-interactive and to prevent its value from being
submitted. The autofocus
attribute controls focus.
The indeterminate IDL
attribute must initially be set to false. On getting, it must return
the last value it was set to. On setting, it must be set to the new
value. It has no effect except for changing the appearance of checkbox controls.
The accept, alt, autocomplete, max, min, multiple, pattern, placeholder, required, size, src, step, and type IDL attributes must
reflect the respective content attributes of the same
name. The maxLength IDL
attribute must reflect the maxlength content attribute,
limited to only non-negative numbers. The readOnly IDL attribute
must reflect the readonly content attribute. The
defaultChecked
IDL attribute must reflect the checked content attribute. The
defaultValue
IDL attribute must reflect the value content attribute.
The willValidate, validity, and validationMessage
attributes, and the checkValidity() and setCustomValidity()
methods, are part of the constraint validation API. The
labels attribute provides a list
of the element's labels. The select(), selectionStart,
selectionEnd,
and setSelectionRange()
methods and attributes expose the element's text selection. The
autofocus, disabled, form, and name IDL attributes are part of the
element's forms API.