Forms allow unscripted client-server interaction: given a form, a user can provide data, submit it to the server, and have the server act on it accordingly (e.g. returning the results of a search or calculation). The elements used in forms can also be used for user interaction with no associated submission mechanism, in conjunction with scripts.
Mostly for historical reasons, elements in this section fall into several overlapping (but subtly different) categories in addition to the usual ones like flow content, phrasing content, and interactive content.
A number of the elements are form-associated elements, which means they can have a
form owner and, to expose this, have a form
content attribute with a matching
form
DOM attribute.
The form-associated elements fall into several subcategories:
form
element is submitted.form
element is reset.form.elements
and fieldset.elements
APIs.label
elements.In addition, some submittable elements can be, depending on their attributes, buttons. The prose below defines when an element is a button. Some buttons are specifically submit buttons.
The object
element is also a
form-associated element and can, with the use of a
suitable plugin, partake in form
submission.
form
elementform
element descendants.accept-charset
action
autocomplete
enctype
method
name
novalidate
target
[Callable=namedItem] interface HTMLFormElement : HTMLElement { attribute DOMString acceptCharset; attribute DOMString action; attribute boolean autocomplete; attribute DOMString enctype; attribute DOMString method; attribute DOMString name; attribute boolean novalidate; attribute DOMString target; readonly attribute HTMLFormControlsCollection elements; readonly attribute long length; [IndexGetter] any item(in DOMString name); [NameGetter=OverrideBuiltins] any namedItem(in DOMString name); void submit(); void reset(); boolean checkValidity(); void dispatchFormInput(); void dispatchFormChange(); };
The form
element represents a
collection of form-associated
elements, some of which can represent editable values that
can be submitted to a server for processing.
The accept-charset
attribute gives the character encodings that are to be used for the
submission. If specified, the value must be an ordered set of
unique space-separated tokens, and each token must be the
preferred name of an ASCII-compatible character
encoding. [IANACHARSET]
The name
attribute
represents the form
's name within the forms
collection. The value must not be the
empty string, and the value must be unique amongst the
form
elements in the forms
collection that it is in, if any.
The autocomplete
attribute is an enumerated attribute. The attribute has
two states. The on
keyword maps to the on state, and the
off
keyword maps to
the off
state. The attribute may also be omitted. The missing value
default is the on state. The off state indicates
that by default, input
elements in the form will have
their resulting autocompletion state set to off; the on state indicates
that by default, input
elements in the form will have
their resulting autocompletion state set to on.
The action
, enctype
, method
, novalidate
, and target
attributes are attributes
for form submission.
elements
Returns an HTMLCollection
of the form controls in
the form (excluding image buttons for historical reasons).
length
Returns the number of form controls in the form (excluding image buttons for historical reasons).
item
(index)Returns the indexth element in the form (excluding image buttons for historical reasons).
namedItem
(name)Returns the form control in the form with the given ID or name
(excluding image buttons for
historical reasons).
Once an element has been referenced using a particular name,
that name will continue being available as a way to reference that
element in this method, even if the element's actual ID or name
changes, for as long as the
element remains in the Document
.
If there are multiple matching items, then a
NodeList
object containing all those elements is
returned.
Returns null if no element with that ID or name
could be found.
submit
()Submits the form.
reset
()Resets the form.
checkValidity
()Returns true if the form's controls are all valid; otherwise, returns false.
dispatchFormInput
()Dispatches a forminput
event at all the form controls.
dispatchFormChange
()Dispatches a formchange
event at all the form controls.
The autocomplete
and
name
DOM attributes
must reflect the respective content attributes of the
same name.
The acceptCharset
DOM
attribute must reflect the accept-charset
content
attribute.
The elements
DOM attribute must return an HTMLFormControlsCollection
rooted at the Document
node, whose filter matches listed elements whose form
owner is the form
element, with the exception of
input
elements whose type
attribute is in the Image Button state, which must,
for historical reasons, be excluded from this particular
collection.
The length
DOM
attribute must return the number of nodes represented by the elements
collection.
The
indices of the supported indexed properties at any
instant are the indices supported by the object returned by the
elements
attribute at that
instant.
The item(index)
method must return the value
returned by the method of the same name on the elements
collection, when invoked
with the same argument.
Each form
element has a mapping of names to elements
called the past names map. It is used to persist names of
controls even when they change names.
The names of the supported named properties are the
union of the names currently supported by the object returned by the
elements
attribute, and the
names currently in the past names map.
The namedItem(name)
method, when called, must run the
following steps:
If name is one of the names of the
supported named properties of the object returned by the
elements
attribute, then
run these substeps:
Let candidate be the object returned
by the namedItem()
method on the object returned by the elements
attribute when passed
the name argument.
If candidate is an element, then add a
mapping from name to candidate in the form
element's
past names map, replacing the previous entry with
the same name, if any.
Return candidate and abort these steps.
Otherwise, name is the name of one of
the entries in the form
element's past names
map: return the object associated with name in that map.
If an element listed in the form
element's past
names map is removed from the Document
, then its
entries must be removed from the map.
The submit()
method, when invoked, must submit the form
element from the form
element itself.
The reset()
method, when invoked, must reset the form
element.
If the checkValidity()
method is invoked, the user agent must statically validate the
constraints of the form
element, and return true
if the constraint validation return a positive result, and
false if it returned a negative result.
If the dispatchFormInput()
method is invoked, the user agent must broadcast forminput
events from the
form
element.
If the dispatchFormChange()
method is invoked, the user agent must broadcast formchange
events from the
form
element.
fieldset
elementlegend
element followed by flow content.disabled
form
name
interface HTMLFieldSetElement : HTMLElement { attribute boolean disabled; readonly attribute HTMLFormElement form; attribute DOMString name; readonly attribute DOMString type; readonly attribute HTMLFormControlsCollection elements; readonly attribute boolean willValidate; readonly attribute ValidityState validity; readonly attribute DOMString validationMessage; boolean checkValidity(); void setCustomValidity(in DOMString error); };
The fieldset
element represents a set of form
controls grouped under a common name.
The name of the group is given by the first legend
element that is a child of the fieldset
element. The
remainder of the descendants form the group.
The disabled
attribute, when specified, causes all the form control descendants
of the fieldset
element to be disabled.
The form
attribute is used to
explicitly associate the fieldset
element with its
form owner. The name
attribute represents the element's name.
type
Returns the string "fieldset".
elements
Returns an HTMLCollection
of the form controls in
the element.
The disabled
DOM
attribute must reflect the content attribute of the
same name.
The type
DOM
attribute must return the string "fieldset
".
The elements
DOM
attribute must return an HTMLFormControlsCollection
rooted at the fieldset
element, whose filter matches
listed elements.
The willValidate
,
validity
, and validationMessage
attributes, and the checkValidity()
and
setCustomValidity()
methods, are part of the constraint validation API.
Constraint validation: fieldset
elements are always barred from constraint
validation.
label
elementlabel
elements.form
for
interface HTMLLabelElement : HTMLElement { readonly attribute HTMLFormElement form; attribute DOMString htmlFor; readonly attribute HTMLElement control; };
The label
represents a caption in a
user interface. The caption can be associated with a specific form
control, known as the label
element's labeled control, either using for
attribute, or by putting the form
control inside the label
element itself.
Unless otherwise specified by the following rules, a
label
element has no labeled control.
The for
attribute
may be specified to indicate a form control with which the caption
is to be associated. If the attribute is specified, the attribute's
value must be the ID of a labelable
form-associated element in the same Document
as
the label
element. If the attribute
is specified and there is an element in the Document
whose ID is equal to the value of the for
attribute, and the first such
element is a labelable form-associated
element, then that element is the label
element's labeled control.
If the for
attribute is not
specified, but the label
element has a labelable
form-associated element descendant, then the first such
descendant in tree order is the label
element's labeled control.
The label
element's exact default presentation and
behavior, in particular what its activation behavior
might be, if anything, should match the platform's label
behavior.
For example, on platforms where clicking a checkbox label checks
the checkbox, clicking the label
in the following
snippet could trigger the user agent to run synthetic click
activation steps on the input
element, as if
the element itself had been triggered by the user:
<label><input type=checkbox name=lost> Lost</label>
On other platforms, the behavior might be just to focus the control, or do nothing.
control
Returns the form control that is associated with this element.
The form
attribute is used to
explicitly associate the label
element with its
form owner.
The htmlFor
DOM
attribute must reflect the for
content attribute.
The control
DOM
attribute must return the label
element's labeled
control, if any, or null if there isn't one.
labels
Returns a NodeList
of all the label
elements that the form control is associated with.
Labelable form-associated
elements have a NodeList
object associated with
them that represents the list of label
elements, in
tree order, whose labeled control is the
element in question. The labels
DOM attribute of
labelable form-associated
elements, on getting, must return that NodeList
object.
input
elementtype
attribute is not in the Hidden state: Interactive content.accept
alt
autocomplete
autofocus
checked
disabled
form
formaction
formenctype
formmethod
formnovalidate
formtarget
height
list
max
maxlength
min
multiple
name
pattern
placeholder
readonly
required
size
src
step
type
value
width
interface HTMLInputElement : HTMLElement { attribute DOMString accept; attribute DOMString alt; attribute boolean autocomplete; attribute boolean autofocus; attribute boolean defaultChecked; attribute boolean checked; attribute boolean disabled; readonly attribute HTMLFormElement form; 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 float valueAsNumber; readonly attribute HTMLOptionElement selectedOption; attribute DOMString width; void stepUp(in long n); void stepDown(in 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 |
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
, readonly
, required
, size
, src
, step
, and width
attributes apply to an
input
element depends on the state of its type
attribute. Similarly, the checked
, valueAsDate
, valueAsNumber
, list
, and selectedOption
DOM
attributes, and the stepUp()
and stepDown()
methods, are
specific to certain states. The following table is non-normative and summarises which content
attributes, DOM attributes, and methods apply to each state:
Hidden | Text, Search, URL | 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 | ||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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 | · |
checked
| · | · | · | · | · | · | · | · | Yes | · | · | · | · |
value
| value | 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 | · | · | · | · | · | · |
input event
| · | Yes | 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
DOM 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
DOM
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 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 has a boolean mutability flag. When it is
true, the element is said to be mutable, and when it is
false the element is immutable. Unless
otherwise specified, an input
element is always mutable. Unless 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.
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
DOM
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
DOM attributes must
reflect the respective content attributes of the same
name. The maxLength
DOM
attribute must reflect the maxlength
content attribute. The
readOnly
DOM
attribute must reflect the readonly
content attribute. The
defaultChecked
DOM attribute must reflect the checked
content attribute. The
defaultValue
DOM 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 label
s. The select()
, selectionStart
,
selectionEnd
,
and setSelectionRange()
methods and attributes expose the element's text selection.
type
attributeThe input
element represents a value
that is not intended to be examined or manipulated by the user.
Constraint validation: If an input
element's type
attribute is in
the Hidden state, it is
barred from constraint validation.
If the name
attribute is
present and has a value that is a case-sensitive match
for the string "_charset_
", then the element's
value
attribute must be
omitted.
The
value
DOM attribute applies to this element and is
in mode value.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
autocomplete
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
list
,
max
,
maxlength
,
min
,
multiple
,
pattern
,
placeholder
,
readonly
,
required
,
size
,
src
,
step
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
list
,
selectedOption
,
selectionStart
,
selectionEnd
,
valueAsDate
, and
valueAsNumber
DOM attributes;
select()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
When an input
element's type
attribute is in the Text state or the Search state, the rules in
this section apply.
The input
element represents a one line
plain text edit control for the element's value.
If the element is mutable, its value should be editable by the user. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the element's value.
The value
attribute, if
specified, must have a value that contains no U+000A LINE FEED (LF)
or U+000D CARRIAGE RETURN (CR) characters.
The value sanitization algorithm is as follows: Strip line breaks from the value.
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
,
list
,
maxlength
,
pattern
,
placeholder
,
readonly
,
required
, and
size
content attributes;
list
,
selectedOption
,
selectionStart
,
selectionEnd
, and
value
DOM attributes;
select()
and
setSelectionRange()
methods.
The value
DOM attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
max
,
min
,
multiple
,
src
,
step
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
valueAsDate
, and
valueAsNumber
DOM attributes;
stepDown()
and
stepUp()
methods.
The input
element represents a control
for editing a single absolute URL given in the
element's value.
If the is mutable, the user agent should allow the user to change the URL represented by its value. User agents may allow the user to set the value to a string that is not a valid absolute URL, but may also or instead automatically escape characters entered by the user so that the value is always a valid absolute URL (even if that isn't the actual value seen and edited by the user in the interface). User agents should allow the user to set the value to the empty string. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the value.
The value
attribute, if
specified, must have a value that is a valid absolute URL.
The value sanitization algorithm is as follows: Strip line breaks from the value.
Constraint validation: While the value of the element is not a valid absolute URL, the element is suffering from a type mismatch.
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
,
list
,
maxlength
,
pattern
,
placeholder
,
readonly
,
required
, and
size
content attributes;
list
,
selectedOption
,
selectionStart
,
selectionEnd
, and
value
DOM attributes;
select()
and
setSelectionRange()
methods.
The value
DOM attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
max
,
min
,
multiple
,
src
,
step
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
valueAsDate
, and
valueAsNumber
DOM attributes;
stepDown()
and
stepUp()
methods.
The input
element represents a control
for editing a list of e-mail addresses given in the element's value.
If the element is mutable,
the user agent should allow the user to change the e-mail addresses
represented by its value. If
the multiple
attribute is
specified, then the user agent should allow the user to select or
provide multiple addresses; otherwise, the user agent should act in
a manner consistent with expecting the user to provide a single
e-mail address. User agents may allow the user to set the value to a string that is not an
valid e-mail address list. User agents should allow the
user to set the value to the
empty string. User agents must not allow users to insert U+000A LINE
FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the value. User agents may transform the
value for display and editing
(e.g. converting punycode in the value to IDN in the display and vice
versa).
If the multiple
attribute is specified on the element, then the value
attribute, if specified, must
have a value that is a valid e-mail address list;
otherwise, the value
attribute, if specified, must have a value that is a single
valid e-mail address.
The value sanitization algorithm is as follows: Strip line breaks from the value.
Constraint validation: If the multiple
attribute is specified
on the element, then, while the value of the element is not a
valid e-mail address list, the element is
suffering from a type mismatch; otherwise, while the
value of the element is not a
single valid e-mail address, the element is
suffering from a type mismatch.
A valid e-mail address list is a set of comma-separated tokens, where each token is itself a valid e-mail address. To obtain the list of tokens from a valid e-mail address list, the user agent must split the string on commas.
A valid e-mail address is a string that matches the
production dot-atom "@" dot-atom
where dot-atom
is defined in RFC 2822 section
3.2.4, excluding the CFWS
production everywhere. [RFC2822]
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
,
list
,
maxlength
,
multiple
,
pattern
,
placeholder
,
readonly
,
required
, and
size
content attributes;
list
,
selectedOption
,
selectionStart
,
selectionEnd
, and
value
DOM attributes;
select()
and
setSelectionRange()
methods.
The value
DOM attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
max
,
min
,
src
,
step
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
valueAsDate
, and
valueAsNumber
DOM attributes;
stepDown()
and
stepUp()
methods.
The input
element represents a one line
plain text edit control for the element's value. The user agent should obscure
the value so that people other than the user cannot see it.
If the element is mutable, its value should be editable by the user. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the value.
The value
attribute, if
specified, must have a value that contains no U+000A LINE FEED (LF)
or U+000D CARRIAGE RETURN (CR) characters.
The value sanitization algorithm is as follows: Strip line breaks from the value.
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
,
maxlength
,
pattern
,
placeholder
,
readonly
,
required
, and
size
content attributes;
selectionStart
,
selectionEnd
, and
value
DOM attributes;
select()
, and
setSelectionRange()
methods.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
list
,
max
,
min
,
multiple
,
src
,
step
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
list
,
selectedOption
,
valueAsDate
, and
valueAsNumber
DOM attributes;
stepDown()
and
stepUp()
methods.
When an input
element's type
attribute is in the Date and Time state, the
rules in this section apply.
The input
element represents a control
for setting the element's value to a string representing a
specific global date and
time. User agents may display the date and
time in whatever time zone is appropriate for the user.
If the element is mutable, the user agent should allow the user to change the global date and time represented by its value, as obtained by parsing a global date and time from it. User agents must not allow the user to set the value to a string that is not a valid global date and time string expressed in UTC, though user agents may allow the user to set and view the time in another time zone and silently translate the time to and from the UTC time zone in the value. If the user agent provides a user interface for selecting a global date and time, then the value must be set to a valid global date and time string expressed in UTC representing the user's selection. User agents should allow the user to set the value to the empty string.
The value
attribute, if
specified, must have a value that is a valid global date and
time string.
The value sanitization algorithm is as follows: If the value of the element is a valid global date and time string, then adjust the time so that the value represents the same point in time but expressed in the UTC time zone, otherwise, set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid global date and
time string. The max
attribute, if specified, must have a value that is a valid
global date and time string.
The step
attribute is
expressed in seconds. The step scale factor is 1000
(which converts the seconds to milliseconds, as used in the other
algorithms). The default step is 60
seconds.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest global date and time for which the element would not suffer from a step mismatch.
The algorithm to convert a
string to a number, given a string input,
is as follows: If parsing a global date and time from input results in an error, then return an error;
otherwise, return the number of milliseconds elapsed from midnight
UTC on the morning of 1970-01-01 (the time represented by the value
"1970-01-01T00:00:00.0Z
") to the parsed global date and time, ignoring leap
seconds.
The algorithm to convert a
number to a string, given a number input,
is as follows: Return a valid global date and time
string expressed in UTC that represents the global date and time that is input milliseconds after midnight UTC on the morning
of 1970-01-01 (the time represented by the value "1970-01-01T00:00:00.0Z
").
The algorithm to convert a
string to a Date
object, given a string input, is as follows: If parsing a global date and time
from input results in an error, then return an
error; otherwise, return a Date
object representing the
parsed global date and time,
expressed in UTC.
The algorithm to convert a
Date
object to a string, given a
Date
object input, is as
follows: Return a valid global date and time
string expressed in UTC that represents the global date and time that is
represented by input.
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
,
valueAsDate
,
valueAsNumber
, and
selectedOption
DOM attributes;
stepDown()
and
stepUp()
methods.
The value
DOM attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
selectionStart
, and
selectionEnd
DOM attributes;
select()
and
setSelectionRange()
methods.
The input
element represents a control
for setting the element's value to a string representing a
specific date.
If the element is mutable, the user agent should allow the user to change the date represented by its value, as obtained by parsing a date from it. User agents must not allow the user to set the value to a string that is not a valid date string. If the user agent provides a user interface for selecting a date, then the value must be set to a valid date string representing the user's selection. User agents should allow the user to set the value to the empty string.
The value
attribute, if
specified, must have a value that is a valid date
string.
The value sanitization algorithm is as follows: If the value of the element is not a valid date string, then set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid date
string. The max
attribute, if specified, must have a value that is a valid
date string.
The step
attribute is
expressed in days. The step scale factor is
86,400,000 (which converts the days to milliseconds, as used in the
other algorithms). The default step is 1 day.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest date for which the element would not suffer from a step mismatch.
The algorithm to convert a
string to a number, given a string input,
is as follows: If parsing
a date from input results in an error,
then return an error; otherwise, return the number of milliseconds
elapsed from midnight UTC on the morning of 1970-01-01 (the time
represented by the value "1970-01-01T00:00:00.0Z
") to midnight UTC on the
morning of the parsed date,
ignoring leap seconds.
The algorithm to convert a
number to a string, given a number input,
is as follows: Return a valid date string that
represents the date that, in UTC,
is current input milliseconds after midnight UTC
on the morning of 1970-01-01 (the time represented by the value
"1970-01-01T00:00:00.0Z
").
The algorithm to convert a
string to a Date
object, given a string input, is as follows: If parsing a date from input
results in an error, then return an error; otherwise, return a
Date
object representing midnight UTC on the morning of
the parsed date.
The algorithm to convert a
Date
object to a string, given a
Date
object input, is as
follows: Return a valid date string that
represents the date current at the
time represented by input in the UTC
time zone.
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
,
valueAsDate
,
valueAsNumber
, and
selectedOption
DOM attributes;
stepDown()
and
stepUp()
methods.
The value
DOM attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
selectionStart
, and
selectionEnd
DOM attributes;
select()
and
setSelectionRange()
methods.
The input
element represents a control
for setting the element's value to a string representing a
specific month.
If the element is mutable, the user agent should allow the user to change the month represented by its value, as obtained by parsing a month from it. User agents must not allow the user to set the value to a string that is not a valid month string. If the user agent provides a user interface for selecting a month, then the value must be set to a valid month string representing the user's selection. User agents should allow the user to set the value to the empty string.
The value
attribute, if
specified, must have a value that is a valid month
string.
The value sanitization algorithm is as follows: If the value of the element is not a valid month string, then set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid month
string. The max
attribute, if specified, must have a value that is a valid
month string.
The step
attribute is
expressed in months. The step scale factor is 1
(there is no conversion needed as the algorithms use months).
The default step is
1 month.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest month for which the element would not suffer from a step mismatch.
The algorithm to convert a string to a number, given a string input, is as follows: If parsing a month time from input results in an error, then return an error; otherwise, return the number of months between January 1970 and the parsed month.
The algorithm to convert a number to a string, given a number input, is as follows: Return a valid month string that represents the month that has input months between it and January 1970.
The algorithm to convert a
string to a Date
object, given a string input, is as follows: If parsing a month from input results in an error, then return an error;
otherwise, return a Date
object representing midnight
UTC on the morning of the first day of the parsed month.
The algorithm to convert a
Date
object to a string, given a
Date
object input, is as
follows: Return a valid month string that
represents the month current at
the time represented by input in the UTC
time zone.
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
,
valueAsDate
,
valueAsNumber
, and
selectedOption
DOM attributes;
stepDown()
and
stepUp()
methods.
The value
DOM attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
selectionStart
, and
selectionEnd
DOM attributes;
select()
and
setSelectionRange()
methods.
The input
element represents a control
for setting the element's value to a string representing a
specific week.
If the element is mutable, the user agent should allow the user to change the week represented by its value, as obtained by parsing a week from it. User agents must not allow the user to set the value to a string that is not a valid week string. If the user agent provides a user interface for selecting a week, then the value must be set to a valid week string representing the user's selection. User agents should allow the user to set the value to the empty string.
The value
attribute, if
specified, must have a value that is a valid week
string.
The value sanitization algorithm is as follows: If the value of the element is not a valid week string, then set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid week
string. The max
attribute, if specified, must have a value that is a valid
week string.
The step
attribute is
expressed in weeks. The step scale factor is
604,800,000 (which converts the weeks to milliseconds, as used in
the other algorithms). The default step is 1
week.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest week for which the element would not suffer from a step mismatch.
The algorithm to convert a
string to a number, given a string input,
is as follows: If parsing
a week string from input results in an
error, then return an error; otherwise, return the number of
milliseconds elapsed from midnight UTC on the morning of 1970-01-01
(the time represented by the value "1970-01-01T00:00:00.0Z
") to midnight UTC on the
morning of the Monday of the parsed week, ignoring leap seconds.
The algorithm to convert a
number to a string, given a number input,
is as follows: Return a valid week string that
represents the week that, in UTC,
is current input milliseconds after midnight UTC
on the morning of 1970-01-01 (the time represented by the value
"1970-01-01T00:00:00.0Z
").
The algorithm to convert a
string to a Date
object, given a string input, is as follows: If parsing a week from input
results in an error, then return an error; otherwise, return a
Date
object representing midnight UTC on the morning of
the Monday of the parsed week.
The algorithm to convert a
Date
object to a string, given a
Date
object input, is as
follows: Return a valid week string that
represents the week current at the
time represented by input in the UTC
time zone.
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
,
valueAsDate
,
valueAsNumber
, and
selectedOption
DOM attributes;
stepDown()
and
stepUp()
methods.
The value
DOM attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
selectionStart
, and
selectionEnd
DOM attributes;
select()
and
setSelectionRange()
methods.
The input
element represents a control
for setting the element's value to a string representing a
specific time.
If the element is mutable, the user agent should allow the user to change the time represented by its value, as obtained by parsing a time from it. User agents must not allow the user to set the value to a string that is not a valid time string. If the user agent provides a user interface for selecting a time, then the value must be set to a valid time string representing the user's selection. User agents should allow the user to set the value to the empty string.
The value
attribute, if
specified, must have a value that is a valid time
string.
The value sanitization algorithm is as follows: If the value of the element is not a valid time string, then set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid time
string. The max
attribute, if specified, must have a value that is a valid
time string.
The step
attribute is
expressed in seconds. The step scale factor is 1000
(which converts the seconds to milliseconds, as used in the other
algorithms). The default step is 60
seconds.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest time for which the element would not suffer from a step mismatch.
The algorithm to convert a string to a number, given a string input, is as follows: If parsing a time from input results in an error, then return an error; otherwise, return the number of milliseconds elapsed from midnight to the parsed time on a day with no time changes.
The algorithm to convert a number to a string, given a number input, is as follows: Return a valid time string that represents the time that is input milliseconds after midnight on a day with no time changes.
The algorithm to convert a
string to a Date
object, given a string input, is as follows: If parsing a time from input
results in an error, then return an error; otherwise, return a
Date
object representing the parsed time in UTC on 1970-01-01.
The algorithm to convert a
Date
object to a string, given a
Date
object input, is as
follows: Return a valid time string that
represents the UTC time component
that is represented by input.
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
,
valueAsDate
,
valueAsNumber
, and
selectedOption
DOM attributes;
stepDown()
and
stepUp()
methods.
The value
DOM attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
selectionStart
, and
selectionEnd
DOM attributes;
select()
and
setSelectionRange()
methods.
When an input
element's type
attribute is in the Local Date and Time
state, the rules in this section apply.
The input
element represents a control
for setting the element's value to a string representing a
local date and time,
with no time zone information.
If the element is mutable, the user agent should allow the user to change the date and time represented by its value, as obtained by parsing a date and time from it. User agents must not allow the user to set the value to a string that is not a valid local date and time string. If the user agent provides a user interface for selecting a local date and time, then the value must be set to a valid local date and time string representing the user's selection. User agents should allow the user to set the value to the empty string.
The value
attribute, if
specified, must have a value that is a valid local date and
time string.
The value sanitization algorithm is as follows: If the value of the element is not a valid local date and time string, then set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid local date and
time string. The max
attribute, if specified, must have a value that is a valid
local date and time string.
The step
attribute is
expressed in seconds. The step scale factor is 1000
(which converts the seconds to milliseconds, as used in the other
algorithms). The default step is 60
seconds.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest local date and time for which the element would not suffer from a step mismatch.
The algorithm to convert a
string to a number, given a string input,
is as follows: If parsing a date and time from input results in an error, then return an error;
otherwise, return the number of milliseconds elapsed from midnight
on the morning of 1970-01-01 (the time represented by the value
"1970-01-01T00:00:00.0
") to the parsed local date and time, ignoring
leap seconds.
The algorithm to convert a
number to a string, given a number input,
is as follows: Return a valid local date and time
string that represents the date and time that is input milliseconds after midnight on the morning of
1970-01-01 (the time represented by the value "1970-01-01T00:00:00.0
").
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
,
valueAsNumber
, and
selectedOption
DOM attributes;
stepDown()
and
stepUp()
methods.
The value
DOM attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
selectionStart
,
selectionEnd
, and
valueAsDate
DOM attributes;
select()
and
setSelectionRange()
methods.
The input
element represents a control
for setting the element's value to a string representing a
number.
If the element is mutable, the user agent should allow the user to change the number represented by its value, as obtained from applying the rules for parsing floating point number values to it. User agents must not allow the user to set the value to a string that is not a valid floating point number. If the user agent provides a user interface for selecting a number, then the value must be set to the best representation of the floating point number representing the user's selection. User agents should allow the user to set the value to the empty string.
The value
attribute, if
specified, must have a value that is a valid floating point
number.
The value sanitization algorithm is as follows: If the value of the element is not a valid floating point number, then set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid floating point
number. The max
attribute, if specified, must have a value that is a valid
floating point number.
The step scale factor is
1. The default
step is 1 (allowing only integers, unless the min
attribute has a non-integer
value).
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest number for which the element would not suffer from a step mismatch.
The algorithm to convert a string to a number, given a string input, is as follows: If applying the rules for parsing floating point number values to input results in an error, then return an error; otherwise, return the resulting number.
The algorithm to convert a number to a string, given a number input, is as follows: Return a valid floating point number that represents input.
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
,
valueAsNumber
, and
selectedOption
DOM attributes;
stepDown()
and
stepUp()
methods.
The value
DOM attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
selectionStart
,
selectionEnd
, and
valueAsDate
DOM attributes;
select()
and
setSelectionRange()
methods.
The input
element represents a control
for setting the element's value to a string representing a
number, but with the caveat that the exact value is not important,
letting UAs provide a simpler interface than they do for the Number state.
In this state, the range and step constraints are enforced even during user input, and there is no way to set the value to the empty string.
If the element is mutable, the user agent should allow the user to change the number represented by its value, as obtained from applying the rules for parsing floating point number values to it. User agents must not allow the user to set the value to a string that is not a valid floating point number. If the user agent provides a user interface for selecting a number, then the value must be set to a best representation of the floating point number representing the user's selection. User agents must not allow the user to set the value to the empty string.
The value
attribute, if
specified, must have a value that is a valid floating point
number.
The value sanitization algorithm is as follows: If the value of the element is not a valid floating point number, then set it to a valid floating point number that represents the default value.
The min
attribute, if
specified, must have a value that is a valid floating point
number. The default
minimum is 0. The max
attribute, if specified, must have a value that is a valid
floating point number. The default maximum is 100.
The default value is the minimum plus half the difference between the minimum and the maximum, unless the maximum is less than the minimum, in which case the default value is the minimum.
When the element is suffering from an underflow, the user agent must set the element's value to a valid floating point number that represents the minimum.
When the element is suffering from an overflow, if the maximum is not less than the minimum, the user agent must set the element's value to a valid floating point number that represents the maximum.
The step scale factor is
1. The default
step is 1 (allowing only integers, unless the min
attribute has a non-integer
value).
When the element is suffering from a step mismatch, the user agent must round the element's value to the nearest number for which the element would not suffer from a step mismatch, and which is greater than or equal to the minimum, and, if the maximum is not less than the minimum, which is less than or equal to the maximum.
The algorithm to convert a string to a number, given a string input, is as follows: If applying the rules for parsing floating point number values to input results in an error, then return an error; otherwise, return the resulting number.
The algorithm to convert a number to a string, given a number input, is as follows: Return a valid floating point number that represents input.
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
, and
step
content attributes;
list
,
value
,
valueAsNumber
, and
selectedOption
DOM attributes;
stepDown()
and
stepUp()
methods.
The value
DOM attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
readonly
,
required
,
size
,
src
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
selectionStart
,
selectionEnd
, and
valueAsDate
DOM attributes;
select()
and
setSelectionRange()
methods.
The input
element represents a color
well control, for setting the element's value to a string representing a
simple color.
In this state, there is always a color picked, and there is no way to set the value to the empty string.
If the element is mutable, the user agent should allow the user to change the color represented by its value, as obtained from applying the rules for parsing simple color values to it. User agents must not allow the user to set the value to a string that is not a valid lowercase simple color. If the user agent provides a user interface for selecting a color, then the value must be set to the result of using the rules for serializing simple color values to the user's selection. User agents must not allow the user to set the value to the empty string.
The value
attribute, if
specified, must have a value that is a valid simple
color.
The value sanitization algorithm is as
follows: If the value
of the element is a valid simple color, then set it to
the value of the element
converted to lowercase; otherwise, set it to the string
"#000000
".
The following common input
element content
attributes, DOM attributes, and methods apply to the element:
autocomplete
and
list
content attributes;
list
,
value
, and
selectedOption
DOM attributes.
The value
DOM attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
max
,
min
,
multiple
,
pattern
,
placeholder
,
readonly
,
required
,
size
,
src
,
step
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
selectionStart
,
selectionEnd
,
valueAsDate
, and
valueAsNumber
DOM attributes;
select()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
The input
element represents a
two-state control that represents the element's checkedness state. If the
element's checkedness state
is true, the control represents a positive selection, and if it is
false, a negative selection. If the element's indeterminate
DOM attribute
is set to true, then the control's selection should be obscured as
if the control was in a third, indeterminate, state.
The control is never a true tri-state control, even
if the element's indeterminate
DOM attribute
is set to true. The indeterminate
DOM attribute
only gives the appearance of a third state.
If the element is mutable,
then: The pre-click activation steps consist of setting
the element's checkedness to
its opposite value (i.e. true if it is false, false if it is true),
and of setting the element's indeterminate
DOM attribute
to false. The canceled activation steps consist of
setting the checkedness and
the element's indeterminate
DOM attribute
back to the values they had before the pre-click activation
steps were run. The activation behavior is to
fire a simple event called change
at the element, then
broadcast formchange
events at the element's form owner.
Constraint validation: If the element is required and its checkedness is false, then the element is suffering from being missing.
indeterminate
[ = value ]When set, overrides the rendering of checkbox controls so that the current value is not visible.
The following common input
element content
attributes and DOM attributes apply to the element:
checked
, and
required
content attributes;
checked
and
value
DOM attributes.
The value
DOM attribute is
in mode default/on.
The change
event applies.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
autocomplete
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
list
,
max
,
maxlength
,
min
,
multiple
,
pattern
,
placeholder
,
readonly
,
size
,
src
,
step
, and
width
.
The following DOM attributes and methods do not apply to the
element:
list
,
selectedOption
,
selectionStart
,
selectionEnd
,
valueAsDate
, and
valueAsNumber
DOM attributes;
select()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
The input
event does not
apply.
When an input
element's type
attribute is in the Radio Button state, the rules
in this section apply.
The input
element represents a control
that, when used in conjunction with other input
elements, forms a radio button group in which only one
control can have its checkedness state set to true. If
the element's checkedness
state is true, the control represents the selected control in the
group, and if it is false, it indicates a control in the group that
is not selected.
The radio button group that contains an
input
element a also contains all
the other input
elements b that
fulfill all of the following conditions:
input
element b's type
attribute is in the Radio Button state.name
attribute, and the value of a's name
attribute is a
compatibility caseless match for the value of b's name
attribute.A document must not contain an input
element whose
radio button group contains only that element.
When any of the following events occur, if the element's checkedness state is true after the event, the checkedness state of all the other elements in the same radio button group must be set to false:
name
attribute is added, removed, or changes value.If the element is mutable,
then: The pre-click activation steps consist of setting
the element's checkedness to
true. The canceled activation steps consist of setting
the element's checkedness to
false. The activation behavior is to fire a
simple event called change
at the element, then broadcast formchange
events at the
element's form owner.
Constraint validation: If the element is required and all of the
input
elements in the radio button group have a
checkedness that is
false, then the element is suffering from being
missing.
If none of the radio buttons in a radio button group are checked when they are inserted into the document, then they will all be initially unchecked in the interface, until such time as one of them is checked (either by the user or by script).
The following common input
element content
attributes and DOM attributes apply to the element:
checked
and
required
content attributes;
checked
and
value
DOM attributes.
The value
DOM attribute is
in mode default/on.
The change
event applies.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
autocomplete
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
list
,
max
,
maxlength
,
min
,
multiple
,
pattern
,
placeholder
,
readonly
,
size
,
src
,
step
, and
width
.
The following DOM attributes and methods do not apply to the
element:
list
,
selectedOption
,
selectionStart
,
selectionEnd
,
valueAsDate
, and
valueAsNumber
DOM attributes;
select()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
The input
event does not
apply.
When an input
element's type
attribute is in the File Upload state, the rules in this
section apply.
The input
element represents a list of
selected files,
each file consisting of a file name, a file type, and a file body
(the contents of the file).
If the element is mutable, the user agent should allow the user to change the files on the list, e.g. adding or removing files. Files can be from the filesystem or created on the fly, e.g. a picture taken from a camera connected to the user's device.
Constraint validation: If the element is required and the list of selected files is empty, then the element is suffering from being missing.
Unless the multiple
attribute is set, there must be no more than one file in the list of
selected
files.
The accept
attribute may be specified to provide user agents with a hint of
what file types the server will be able to accept.
If specified, the attribute must consist of a set of comma-separated tokens, each of which must be an ASCII case-insensitive match for one of the following:
audio/*
video/*
image/*
The tokens must not be ASCII case-insensitive matches for any of the other tokens (i.e. duplicates are not allowed). To obtain the list of tokens from the attribute, the user agent must split the attribute value on commas.
User agents should prevent the user from selecting files that are not accepted by one (or more) of these tokens.
The following common input
element content
attributes apply to the element:
accept
,
multiple
, and
required
.
The value
DOM attribute is
in mode filename.
The change
event applies.
The following content attributes must not be specified and do not
apply to the element:
alt
,
autocomplete
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
list
,
max
,
maxlength
,
min
,
pattern
,
placeholder
,
readonly
,
size
,
src
,
step
, and
width
.
The element's value
attribute must be omitted.
The following DOM attributes and methods do not apply to the
element:
checked
,
list
,
selectedOption
,
selectionStart
,
selectionEnd
,
valueAsDate
, and
valueAsNumber
DOM attributes;
select()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
The input
event does not
apply.
When an input
element's type
attribute is in the Submit Button state, the rules
in this section apply.
The input
element represents a button
that, when activated, submits the form. If the
element has a value
attribute,
the button's label must be the value of that attribute; otherwise,
it must be an implementation-defined string that means "Submit" or
some such. The element is a button, specifically a submit button.
If the element is mutable, the user agent should allow the user to activate the element.
The element's activation behavior, if the element
has a form owner, is to submit the form
owner from the input
element; otherwise, it is
to do nothing.
The formaction
, formenctype
, formmethod
, formnovalidate
, and formtarget
attributes are attributes
for form submission.
The following common input
element content
attributes and DOM attributes apply to the element:
formaction
,
formenctype
,
formmethod
,
formnovalidate
, and
formtarget
content attributes;
value
DOM attribute.
The value
DOM attribute is
in mode default.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
autocomplete
,
checked
,
height
,
list
,
max
,
maxlength
,
min
,
multiple
,
pattern
,
placeholder
,
readonly
,
required
size
,
src
,
step
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
list
,
selectedOption
,
selectionStart
,
selectionEnd
,
valueAsDate
, and
valueAsNumber
DOM attributes;
select()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
When an input
element's type
attribute is in the Image Button state, the rules
in this section apply.
The input
element represents either an
image from which a user can select a coordinate and submit the form,
or alternatively a button from which the user can submit the
form. The element is a button,
specifically a submit
button.
The image is given by the src
attribute. The src
attribute must be present, and
must contain a valid URL referencing a non-interactive,
optionally animated, image resource that is neither paged nor
scripted.
When any of the following events occur, unless the user agent
cannot support images, or its support for images has been disabled,
or the user agent only fetches elements on demand, the user agent
must resolve the value of the
src
attribute, relative to the
element, and if that is successful, must fetch the
resulting absolute URL:
input
element's type
attribute is first set to the
Image Button state
(possibly when the element is first created), and the src
attribute is present.input
element's type
attribute is changed back to
the Image Button state,
and the src
attribute is
present, and its value has changed since the last time the type
attribute was in the Image Button state.input
element's type
attribute is in the Image Button state, and the
src
attribute is set or
changed.Fetching the image must delay the load
event.
If the image was successfully obtained, with no network errors, and the image's type is a supported image type, and the image is a valid image of that type, then the image is said to be available. If this is true before the image is completely downloaded, each task that is queued by the networking task source while the image is being fetched must update the presentation of the image appropriately.
The user agents should apply the image sniffing rules to determine the type of the image, with the image's associated Content-Type headers giving the official type. If these rules are not applied, then the type of the image must be the type given by the image's associated Content-Type headers.
User agents must not support non-image resources with the
input
element. User agents must not run executable code
embedded in the image resource. User agents must only display the
first page of a multipage resource. User agents must not allow the
resource to act in an interactive fashion, but should honor any
animation in the resource.
The task that is queued by the networking task
source once the resource has been fetched, must, if the download was successful
and the image is available, queue a task to
fire a load
event on
the input
element; and otherwise, if the fetching
process fails without a response from the remote server, or
completes but the image is not a valid or supported image,
queue a task to fire an error
event on the
input
element.
The alt
attribute
provides the textual label for the alternative button for users and
user agents who cannot use the image. The alt
attribute must also be present,
and must contain a non-empty string.
The input
element supports dimension
attributes.
If the src
attribute is set,
and the image is available and the user agent is configured
to display that image, then: The element represents a
control for selecting a coordinate from
the image specified by the src
attribute; if the element is mutable, the user agent should
allow the user to select this coordinate. The
activation behavior in this case consists of taking the
user's selected coordinate, and
then, if the element has a form owner, submitting the input
element's form owner from the input
element. If the user activates the control without explicitly
selecting a coordinate, then the coordinate (0,0) must be
assumed.
Otherwise, the element represents a submit button
whose label is given by the value of the alt
attribute; if the element is mutable, the user agent should
allow the user to activate the button. The activation
behavior in this case consists of setting the selected
coordinate to (0,0), and then, if the element has a
form owner, submitting the input
element's form owner from the input
element.
The selected coordinate must consist of an x-component and a y-component. The x-component must be greater than or equal to zero, and less than or equal to the rendered width, in CSS pixels, of the image, plus the widths of the left and right borders rendered around the image, if any. The y-component must be greater than or equal to zero, and less than or equal to the rendered height, in CSS pixels, of the image, plus the widths of the top and bottom bordered rendered around the image, if any. The coordinates must be relative to the image's borders, where there are any, and the edge of the image otherwise.
The formaction
, formenctype
, formmethod
, formnovalidate
, and formtarget
attributes are attributes
for form submission.
The following common input
element content
attributes and DOM attributes apply to the element:
alt
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
src
, and
width
content attributes;
value
DOM attribute.
The value
DOM attribute is
in mode default.
The following content attributes must not be specified and do not
apply to the element:
accept
,
autocomplete
,
checked
,
list
,
max
,
maxlength
,
min
,
multiple
,
pattern
,
placeholder
,
readonly
,
required
size
, and
step
.
The element's value
attribute must be omitted.
The following DOM attributes and methods do not apply to the
element:
checked
,
list
,
selectedOption
,
selectionStart
,
selectionEnd
,
valueAsDate
, and
valueAsNumber
DOM attributes;
select()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
Many aspects of this state's behavior are similar to
the behavior of the img
element. Readers are encouraged
to read that section, where many of the same requirements are
described in more detail.
When an input
element's type
attribute is in the Reset Button state, the rules
in this section apply.
The input
element represents a button
that, when activated, resets the form. If the
element has a value
attribute,
the button's label must be the value of that attribute; otherwise,
it must be an implementation-defined string that means "Reset" or
some such. The element is a button.
If the element is mutable, the user agent should allow the user to activate the element.
The element's activation behavior, if the element has a form owner, is to reset the form owner; otherwise, it is to do nothing.
Constraint validation: The element is barred from constraint validation.
The value
DOM attribute
applies to this element and is in mode default.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
autocomplete
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
list
,
max
,
maxlength
,
min
,
multiple
,
pattern
,
placeholder
,
readonly
,
required
size
,
src
,
step
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
list
,
selectedOption
,
selectionStart
,
selectionEnd
,
valueAsDate
, and
valueAsNumber
DOM attributes;
select()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
The input
element represents a button
with no default behavior. If the element has a
value
attribute, the button's
label must be the value of that attribute; otherwise, it must be the
empty string. The element is a button.
If the element is mutable, the user agent should allow the user to activate the element. The element's activation behavior is to do nothing.
Constraint validation: The element is barred from constraint validation.
The value
DOM attribute
applies to this element and is in mode default.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
autocomplete
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
list
,
max
,
maxlength
,
min
,
multiple
,
pattern
,
placeholder
,
readonly
,
required
size
,
src
,
step
, and
width
.
The following DOM attributes and methods do not apply to the
element:
checked
,
list
,
selectedOption
,
selectionStart
,
selectionEnd
,
valueAsDate
, and
valueAsNumber
DOM attributes;
select()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
input
element attributesThese attributes only apply to an input
element if
its type
attribute is in a
state whose definition declares that the attribute applies. When an
attribute doesn't apply to an input
element, user
agents must ignore the attribute.
autocomplete
attributeThe autocomplete
attribute is an enumerated attribute. The attribute has
three states. The on
keyword maps to the on state, and the
off
keyword maps to
the off
state. The attribute may also be omitted. The missing value
default is the default
state.
The off state indicates that the control's input data is either particularly sensitive (for example the activation code for a nuclear weapon) or is a value that will never be reused (for example a one-time-key for a bank login) and the user will therefore have to explicitly enter the data each time, instead of being able to rely on the UA to prefill the value for him.
Conversely, the on state indicates that the value is not particularly sensitive and the user can expect to be able to rely on his user agent to remember values he has entered for that control.
The default state
indicates that the user agent is to use the autocomplete
attribute on the
element's form owner instead.
Each input
element has a resulting
autocompletion state, which is either on or off.
When an input
element's autocomplete
attribute is in
the on state,
when an input
element's autocomplete
attribute is in
the default state,
and the element has no form owner, and when an
input
element's autocomplete
attribute is in
the default state,
and the element's form owner's autocomplete
attribute is in
the on state,
the input
element's resulting autocompletion
state is on. Otherwise, the
input
element's resulting autocompletion
state is off.
When an input
element's resulting
autocompletion state is on, the user agent
may store the value entered by the user so that if the user returns
to the page, the UA can prefill the form. Otherwise, the user agent
should not remember the control's value.
The autocompletion mechanism must be implemented by the user agent acting as if the user had modified the element's value, and must be done at a time where the element is mutable (e.g. just after the element has been inserted into the document, or when the user agent stops parsing).
Banks frequently do not want UAs to prefill login information:
<p>Account: <input type="text" name="ac" autocomplete="off"></p> <p>PIN: <input type="text" name="pin" autocomplete="off"></p>
A user agent may allow the user to override the resulting autocompletion state and set it to always on, always allowing values to be remembered and prefilled), or always off, never remembering values. However, the ability to override the resulting autocompletion state to on should not be trivially accessible, as there are significant security implications for the user if all values are always remembered, regardless of the site's preferences.
list
attributeThe list
attribute is used to identify an element that lists predefined
options suggested to the user.
If present, its value must be the ID of a datalist
element in the same document.
The suggestions source
element is the first element in the document in tree
order to have an ID equal to the value of the list
attribute, if that element is a
datalist
element. If there is no list
attribute, or if there is no
element with that ID, or if the first element with that ID is not a
datalist
element, then there is no suggestions source element.
If there is a suggestions source
element, then, when the user agent is allowing the user to
edit the input
element's value, the user agent should offer
the suggestions represented by the suggestions source element to the
user in a manner suitable for the type of control used. The user
agent may use the suggestion's label to identify the suggestion
if appropriate. If the user selects a suggestion, then the
input
element's value must be set to the selected
suggestion's value, as if
the user had written that value himself.
User agents must filter the suggestions to hide suggestions that
the user would not be allowed to enter as the input
element's value, and should
filter the suggestions to hide suggestions that would cause the
element to not satisfy its
constraints.
If the list
attribute does
not apply, there is no suggestions
source element.
readonly
attributeThe readonly
attribute is a boolean attribute that controls whether
or not the use can edit the form control. When
specified, the element is immutable.
Constraint validation: If the readonly
attribute is specified
on an input
element, the element is barred from
constraint validation.
size
attributeThe size
attribute gives the number of characters that, in a visual
rendering, the user agent is to allow the user to see while editing
the element's value.
The size
attribute, if
specified, must have a value that is a valid non-negative
integer greater than zero.
If the attribute is present, then its value must be parsed using the rules for parsing non-negative integers, and if the result is a number greater than zero, then the user agent should ensure that at least that many characters are visible.
The size
DOM attribute
limited to only positive non-zero numbers.
required
attributeThe required
attribute is a boolean attribute. When specified, the
element is required.
Constraint validation: If the element is required, and its value
DOM attribute applies and is in
the mode value, and the
element is mutable, and the
element's value is the empty
string, then the element is suffering from being
missing.
multiple
attributeThe multiple
attribute is a boolean attribute that indicates whether
the user is to be allowed to specify more than one value.
maxlength
attributeThe maxlength
attribute, when it applies, is a form control maxlength
attribute
controlled by the input
element's dirty value
flag.
If the input
element has a maximum allowed
value length, then the code-point length of the
value of the element's value
attribute must be equal to or less than the element's maximum
allowed value length.
pattern
attributeThe pattern
attribute specifies a regular expression against which the control's
value is to be checked.
If specified, the attribute's value must match the JavaScript Pattern production. [ECMA262]
Constraint validation: If the element's value is not the empty string, and
the element's pattern
attribute is specified and the attribute's value, when compiled as a
JavaScript regular expression with the global
,
ignoreCase
, and multiline
flags disabled (see ECMA262
Edition 3, sections 15.10.7.2 through 15.10.7.4), compiles
successfully but the resulting regular expression does not match the
entirety of the element's value, then the element is
suffering from a pattern mismatch. [ECMA262]
This implies that the regular expression language
used for this attribute is the same as that used in JavaScript,
except that the pattern
attribute must match the entire value, not just any subset (somewhat
as if it implied a ^(?:
at the start of the
pattern and a )$
at the end).
When an input
element has a pattern
attribute specified,
authors should include a title
attribute to give a description of the pattern. User agents may use
the contents of this attribute, if it is present, when informing the
user that the pattern is not matched, or at any other suitable time,
such as in a tooltip or read out by assistive technology when the
control gains focus.
For example, the following snippet:
<label> Part number: <input pattern="[0-9][A-Z]{3}" name="part" title="A part number is a digit followed by three uppercase letters."/> </label>
...could cause the UA to display an alert such as:
part number is a digit followed by three uppercase letters. You cannot complete this form until the field is correct.
When a control has a pattern
attribute, the
title
attribute, if used, must describe the pattern.
Additional information could also be included, so long as it assists
the user in filling in the control. Otherwise, assistive technology
would be impaired.
For instance, if the title attribute contained the caption of the control, assistive technology could end up saying something like The text you have entered does not match the required pattern. Birthday, which is not useful.
UAs may still show the title
in non-error situations
(for example, as a tooltip when hovering over the control), so
authors should be careful not to word title
s as if an
error has necessarily occurred.
min
and max
attributesThe min
and max
attributes indicate
the allowed range of values for the element.
Their syntax is defined by the section that defines the type
attribute's current state.
If the element has a min
attribute, and the result of applying the algorithm to convert a
string to a number to the value of the min
attribute is a number, then that
number is the element's minimum; otherwise, if the type
attribute's current state
defines a default
minimum, then that is the minimum; otherwise, the element has
no minimum.)
Constraint validation: When the element has a minimum, and the result of applying the algorithm to convert a string to a number to the string given by the element's value is a number, and the number obtained from that algorithm is less than the minimum, the element is suffering from an underflow.
The min
attribute also
defines the step
base.
If the element has a max
attribute, and the result of applying the algorithm to convert a
string to a number to the value of the max
attribute is a number, then that
number is the element's maximum; otherwise, if the type
attribute's current state
defines a default
maximum, then that is the maximum; otherwise, the element has
no maximum.)
Constraint validation: When the element has a maximum, and the result of applying the algorithm to convert a string to a number to the string given by the element's value is a number, and the number obtained from that algorithm is more than the maximum, the element is suffering from an overflow.
The max
attribute's value
(the maximum) must not be
less than the min
attribute's
value (its minimum).
If an element has a maximum that is less than its minimum, then so long as the element has a value, it will either be suffering from an underflow or suffering from an overflow.
step
attributeThe step
attribute indicates the granularity that is expected (and required)
of the value, by limiting the
allowed values. The section that defines the
type
attribute's current state
also defines the default
step and the step scale
factor, which are used in processing the attribute as
described below.
The step
attribute, if
specified, must either have a value that is a valid floating
point number that parses to a number that is greater than
zero, or must have a value that is an ASCII
case-insensitive match for the string "any
".
The attribute provides the allowed value step for the element, as follows:
any
", then there is no allowed value step.The step base is the
result of applying the algorithm to convert a
string to a number to the value of the min
attribute, unless the element does
not have a min
attribute
specified or the result of applying that algorithm is an error, in
which case the step base
is zero.
Constraint validation: When the element has an allowed value step, and the result of applying the algorithm to convert a string to a number to the string given by the element's value is a number, and that number subtracted from the step base is not an integral multiple of the allowed value step, the element is suffering from a step mismatch.
placeholder
attributeThe placeholder
attribute represents a short hint (a word or short phrase)
intended to aid the user with data entry. A hint could be a sample
value or a brief description of the expected format. The attribute,
if specified, must have a value that contains no U+000A LINE FEED
(LF) or U+000D CARRIAGE RETURN (CR) characters.
For a longer hint or other advisory text, the title
attribute is more appropriate.
The placeholder
attribute should not be used as an alternative to a
label
.
User agents should present this hint to the user, after having stripped line breaks from it, when the element's value is the empty string and the control is not focused (e.g. by displaying it inside a blank unfocused control).
Here is an example of a mail configuration user interface that
uses the placeholder
attribute:
<fieldset> <legend>Mail Account</legend> <p><label>Name: <input type="text" name="fullname" placeholder="John Ratzenberger"></label></p> <p><label>Address: <input type="email" name="address" placeholder="john@example.net"></label></p> <p><label>Password: <input type="password" name="password"></label></p> <p><label>Description: <input type="text" name="desc" placeholder="My Email Account"></label></p> </fieldset>
input
element APIsvalue
[ = value ]Returns the current value of the form control.
Can be set, to change the value.
Throws an INVALID_ACCESS_ERR
exception if it is
set 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.
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 INVALID_ACCESS_ERR
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 null.
Can be set, to change the value.
Throws an INVALID_ACCESS_ERR
exception if the
control is neither date- or time-based nor numeric.
stepUp
()stepDown
()Changes the form control's value by the value given in the
step
attribute.
Throws INVALID_ACCESS_ERR
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 would take the value out of
range.
list
Returns the datalist
element indicated by the
list
attribute.
selectedOption
Returns the option
element from the
datalist
element indicated by the list
attribute that matches the
form control's value.
The value
DOM
attribute allows scripts to manipulate the value of an input
element. The attribute is in one of the following modes, which
define its behavior:
type
attribute's current state
defines one.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.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.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, it must
throw an INVALID_ACCESS_ERR
exception.The checked
DOM
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 valueAsDate
DOM
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 INVALID_ACCESS_ERR
exception; otherwise, if
the new value is null, 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
DOM
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 INVALID_ACCESS_ERR
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()
and stepUp()
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 INVALID_ACCESS_ERR
exception, and abort these
steps.
If the element has no allowed value step, then throw an
INVALID_ACCESS_ERR
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 INVALID_ACCESS_ERR
exception, and abort
these steps; otherwise, let value be the result
of that algorithm.
Let delta be the allowed value step.
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
INVALID_ACCESS_ERR
exception.
If the element has a maximum, and the value is greater than that maximum, then throw a
INVALID_ACCESS_ERR
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
DOM
attribute must return the current suggestions source element, if
any, or null otherwise.
The selectedOption
DOM attribute must return the first option
element, in
tree order, to be a child of the suggestions source element and
whose value matches the
input
element's value, if any. If there is no suggestions source element, or if
it contains no matching option
element, then the selectedOption
attribute
must return null.
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 called
input
at the input
element, then broadcast forminput
events at the
input
element's form owner. 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 called change
at the
input
element, then broadcast formchange
events at the
input
element's form owner.
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 called input
at the
input
element.input
event
applies, broadcast forminput
events at the
input
element's form owner.change
event
applies, queue a task to fire a simple
event called change
at the
input
element.change
event
applies, broadcast formchange
events at the
input
element's form owner.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 task is the user interaction task source.
button
elementautofocus
disabled
form
formaction
formenctype
formmethod
formnovalidate
formtarget
name
type
value
interface HTMLButtonElement : HTMLElement {
attribute boolean autofocus;
attribute boolean disabled;
readonly attribute HTMLFormElement form;
attribute DOMString formaction;
attribute DOMString formenctype;
attribute DOMString formmethod;
attribute DOMString formnoValidate;
attribute DOMString formtarget;
attribute DOMString name;
attribute DOMString type;
attribute DOMString value;
readonly attribute boolean willValidate;
readonly attribute ValidityState validity;
readonly attribute DOMString validationMessage;
boolean checkValidity();
void setCustomValidity(in DOMString error);
readonly attribute NodeList labels;
};
The button
element represents a
button. If the element is not disabled, then the user agent
should allow the user to activate the button.
The element is a button.
The type
attribute controls the behavior of the button when it is activated.
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 | Brief description |
---|---|---|
submit
| Submit Button | Submits the form. |
reset
| Reset Button | Resets the form. |
button
| Button | Does nothing. |
The missing value default is the Submit Button state.
If the type
attribute is in
the Submit Button
state, the element is specifically a submit button.
If the element is not disabled, the activation
behavior of the button
element is to run the
steps defined in the following list for the current state of the
element's type
attribute.
If the element has a form owner, the element
must submit the form
owner from the button
element.
If the element has a form owner, the element must reset the form owner.
Do nothing.
The form
attribute is used to
explicitly associate the button
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 formaction
, formenctype
, formmethod
, formnovalidate
, and formtarget
attributes are
attributes for form submission.
The value
attribute gives the element's value for the purposes of form
submission. The value
attribute must not be present unless the form
attribute is present. The
element's value is the value
of the element's value
attribute, if there is one, or the empty string otherwise.
A button (and its value) is only included in the form submission if the button itself was used to initiate the form submission.
The value
and
type
DOM attributes
must reflect the respective content attributes of the
same name.
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 label
s.
select
elementoption
or optgroup
elements.autofocus
disabled
form
multiple
name
size
[Callable=namedItem]
interface HTMLSelectElement : HTMLElement {
attribute boolean autofocus;
attribute boolean disabled;
readonly attribute HTMLFormElement form;
attribute boolean multiple;
attribute DOMString name;
attribute boolean size;
readonly attribute DOMString type;
readonly attribute HTMLOptionsCollection options;
attribute unsigned long length;
[IndexGetter] any item(in DOMString name);
[NameGetter] any namedItem(in DOMString name);
void add(in HTMLElement element, [Optional] in HTMLElement before);
void add(in HTMLElement element, in long before);
void remove(in long index);
readonly attribute HTMLCollection selectedOptions;
attribute long selectedIndex;
attribute DOMString value;
readonly attribute boolean willValidate;
readonly attribute ValidityState validity;
readonly attribute DOMString validationMessage;
boolean checkValidity();
void setCustomValidity(in DOMString error);
readonly attribute NodeList labels;
};
The select
element represents a control for
selecting amongst a set of options.
The multiple
attribute is a boolean attribute. If the attribute is
present, then the select
element
represents a control for selecting zero or more options
from the list of
options. If the attribute is absent, then the
select
element represents a control for
selecting a single option from the list of options.
The list of options
for a select
element consists of all the
option
element children of the select
element, and all the option
element children of all the
optgroup
element children of the select
element, in tree order.
The size
attribute gives the number of options to show to the user. The size
attribute, if specified, must
have a value that is a valid non-negative integer
greater than zero. If the multiple
attribute is present,
then the size
attribute's
default value is 4. If the multiple
attribute is absent,
then the size
attribute's
default value is 1.
If the multiple
attribute is absent, and the element is not disabled, then the user agent
should allow the user to pick an option
element in its
list of options that
is itself not disabled. Upon this
option
element being picked (either through a click, or
through unfocusing the element after changing its value, or through
a menu command, or through any
other mechanism), and before the relevant user interaction event is
queued (e.g. before the click
event), the user agent must set the selectedness of the
picked option
element to true and then queue a
task to fire a simple event called change
at the select
element, using the user interaction task source as the
task source, then broadcast formchange
events at the
element's form owner.
If the multiple
attribute is absent, whenever an option
element in the
select
element's list of options has its
selectedness set to
true, and whenever an option
element with its selectedness set to true
is added to the select
element's list of options, the user
agent must set the selectedness of all the
other option
element in its list of options to
false.
If the multiple
attribute is absent, whenever there are no option
elements in the select
element's list of options that have
their selectedness
set to true, the user agent must set the selectedness of the first
option
element in the list of options in
tree order that is not disabled, if any, to
true.
If the multiple
attribute is present, and the element is not disabled, then the user agent
should allow the user to toggle the selectedness of the
option
elements in its list of options that are
themselves not disabled
(either through a click, or through a menu command, or any other
mechanism). Upon the selectedness of one or
more option
elements being changed by the user, and
before the relevant user interaction event is queued (e.g. before a
related click event), the user
agent must queue a task to fire a simple
event called change
at the
select
element, using the user interaction task
source as the task source, then broadcast formchange
events at the
element's form owner.
The reset
algorithm for select
elements is to go through
all the option
elements in the element's list of options, and set
their selectedness
to true if the option
element has a selected
attribute, and false
otherwise.
The form
attribute is used to
explicitly associate the select
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.
type
Returns "select-multiple
" if the element
has a multiple
attribute, and "select-one
"
otherwise.
options
Returns an HTMLOptionsCollection
of the list of options.
length
[ = value ]Returns the number of elements in the list of options.
When set to a smaller number, truncates the number of option
elements in the select
.
When set to a greater number, adds new blank option
elements to the select
.
item
(index)Returns the item with index index from the list of options. The items are sorted in tree order.
Returns null if index is out of range.
namedItem
(name)Returns the item with ID or name
name from the list of options.
If there are multiple matching items, then a NodeList
object containing all those elements is returned.
Returns null if no element with that ID could be found.
add
(element [, before ])Inserts element before the node given by before.
The before argument can be a number, in which case element is inserted before the item with that number, or an element from the list of options, in which case element is inserted before that element.
If before is omitted, null, or a number out of range, then element will be added at the end of the list.
This method will throw a HIERARCHY_REQUEST_ERR
exception if element is an ancestor of the
element into which it is to be inserted. If element is not an option
or
optgroup
element, then the method does nothing.
selectedOptions
Returns an HTMLCollection
of the list of options that are
selected.
selectedIndex
[ = value ]Returns the index of the first selected item, if any, or −1 if there is no selected item.
Can be set, to change the selection.
value
[ = value ]Returns the value of the first selected item, if any, or the empty string if there is no selected item.
Can be set, to change the selection.
The type
DOM
attribute, on getting, must return the string "select-one
" if the multiple
attribute is absent,
and the string "select-multiple
" if the multiple
attribute is
present.
The options
DOM attribute must return an HTMLOptionsCollection
rooted at the select
node, whose filter matches the
elements in the list of
options.
The options
collection is
also mirrored on the HTMLSelectElement
object. The
indices of the supported indexed properties at any
instant are the indices supported by the object returned by the
options
attribute at that
instant. The names of the supported named properties at
any instant are the names supported by the object returned by the
options
attribute at that
instant.
The length
DOM
attribute must return the number of nodes represented by the options
collection. On setting, it
must act like the attribute of the same name on the options
collection.
The item(index)
method must return the value
returned by the method of the same name on the options
collection, when invoked
with the same argument.
The namedItem(name)
method must return the value
returned by the method of the same name on the options
collection, when invoked
with the same argument.
Similarly, the add()
and remove()
methods must
act like their namesake methods on that same options
collection.
The selectedOptions
DOM attribute must return an HTMLCollection
rooted at
the select
node, whose filter matches the elements in
the list of options
that have their selectedness set to
true.
The selectedIndex
DOM attribute, on getting, must return the index of the first
option
element in the list of options in
tree order that has its selectedness set to true,
if any. If there isn't one, then it must return −1.
On setting, the selectedIndex
attribute must
set the selectedness of all the
option
elements in the list of options to false,
and then the option
element in the list of options whose
index is the given new
value, if any, must have its selectedness set to
true.
The value
DOM
attribute, on getting, must return the value of the first
option
element in the list of options in
tree order that has its selectedness set to true,
if any. If there isn't one, then it must return the empty
string.
On setting, the value
attribute must set the selectedness of all the
option
elements in the list of options to false,
and then first the option
element in the list of options, in
tree order, whose value is equal to the given new
value, if any, must have its selectedness set to
true.
The multiple
and size
DOM
attributes must reflect the respective content
attributes of the same name. The size
DOM attribute limited to
only positive non-zero numbers.
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 label
s.
datalist
elementoption
elements.interface HTMLDataListElement : HTMLElement { readonly attribute HTMLCollection options; };
The datalist
element represents a set of
option
elements that represent predefined options for
other controls. The contents of the element represents fallback
content for legacy user agents, intermixed with option
elements that represent the predefined options. In the rendering,
the datalist
element represents
nothing and it, along with its children, should
be hidden.
The datalist
element is hooked up to an
input
element using the list
attribute on the
input
element. The datalist
element can
also be used with a datagrid
element, as the source of
autocompletion hints for editable
cells.
Each option
element that is a descendant of the
datalist
element, that is not disabled, and whose value is a string that isn't the
empty string, represents a suggestion. Each suggestion has a value and a label.
options
Returns an HTMLCollection
of the options
elements of the table.
The options
DOM attribute must return an HTMLCollection
rooted at
the datalist
node, whose filter matches
option
elements.
Constraint validation: If an element has a
datalist
element ancestor, it is barred from
constraint validation.
optgroup
elementselect
element.option
elements.disabled
label
interface HTMLOptGroupElement : HTMLElement { attribute boolean disabled; attribute DOMString label; };
The optgroup
element represents a group of
option
elements with a common label.
The element's group of option
elements consists of
the option
elements that are children of the
optgroup
element.
When showing option
elements in select
elements, user agents should show the option
elements
of such groups as being related to each other and separate from
other option
elements.
The disabled
attribute
is a boolean attribute and can be used to disable a group of
option
elements together.
The label
attribute must be specified. Its value gives the name of the group,
for the purposes of the user interface. User
agents should use this attribute's value when labelling the group of
option
elements in a select
element.
The disabled
and label
attributes must
reflect the respective content attributes of the same
name.
option
elementselect
element.datalist
element.optgroup
element.disabled
label
selected
value
[NamedConstructor=Option(), NamedConstructor=Option(in DOMString text), NamedConstructor=Option(in DOMString text, in DOMString value), NamedConstructor=Option(in DOMString text, in DOMString value, in boolean defaultSelected), NamedConstructor=Option(in DOMString text, in DOMString value, in boolean defaultSelected, in boolean selected)] interface HTMLOptionElement : HTMLElement { attribute boolean disabled; readonly attribute HTMLFormElement form; attribute DOMString label; attribute boolean defaultSelected; attribute boolean selected; attribute DOMString value; readonly attribute DOMString text; readonly attribute long index; };
The option
element represents an option
in a select
element or as part of a list of suggestions
in a datalist
element.
The disabled
attribute is a boolean attribute. An
option
element is disabled if its disabled
attribute is present or
if it is a child of an optgroup
element whose disabled
attribute is
present.
An option
element that is disabled must prevent any click
events that are queued on the user interaction task
source from being dispatched on the element.
The label
attribute provides a label for element. The label of an option
element is the value of the label
attribute, if there is one,
or the textContent
of the element, if there isn't.
The value
attribute provides a value for element. The value of an option
element is the value of the value
attribute, if there is one,
or the textContent
of the element, if there isn't.
The selected
attribute represents the default selectedness of the
element.
The selectedness
of an option
element is a boolean state, initially
false. If the element is disabled, then the element's
selectedness is
always false and cannot be set to true. Unless otherwise specified,
when the element is created, its selectedness must be set
to true if the element has a selected
attribute. Whenever an
option
element's selected
attribute is added, its
selectedness must
be set to true.
The Option()
constructor with two or more arguments overrides the initial state
of the selectedness
state to always be false even if the third argument is true
(implying that a selected
attribute is to be set).
An option
element's index is the number of
option
element that are in the same list of options but that
come before it in tree order. If the
option
element is not in a list of options, then the
option
element's index is zero.
selected
Returns true if the element is selected, and false otherwise.
index
Returns the index of the element in its select
element's options
list.
form
Returns the element's form
element, if any, or
null otherwise.
Option
( [ text [, value [, defaultSelected [, selected ] ] ] ] )Returns a new option
element.
The text argument sets the contents of the element.
The value argument sets the value
attribute.
The defaultSelected argument sets the selected
attribute.
The selected argument sets whether or not the element is selected. If it is omitted, even if the defaultSelected argument is true, the element is not selected.
The disabled
,
label
, and value
DOM attributes
must reflect the respective content attributes of the
same name. The defaultSelected
DOM attribute must reflect the selected
content attribute.
The selected
DOM attribute must return true if the element's selectedness is true, and
false otherwise.
The index
DOM
attribute must return the element's index.
The text
DOM
attribute must return the same value as the textContent
DOM attribute on the element.
The form
DOM
attribute's behavior depends on whether the option
element is in a select
element or not. If the
option
has a select
element as its parent,
or has a colgroup
element as its parent and that
colgroup
element has a select
element as
its parent, then the form
DOM
attribute must return the same value as the form
DOM attribute on that
select
element. Otherwise, it must return null.
Several constructors are provided for creating
HTMLOptionElement
objects (in addition to the factory
methods from DOM Core such as createElement()
): Option()
, Option(text)
, Option(text, value)
, Option(text, value, defaultSelected)
, and Option(text, value, defaultSelected, selected)
. When invoked as constructors,
these must return a new HTMLOptionElement
object (a new
option
element). If the text
argument is present, the new object must have as its only child a
Node
with node type TEXT_NODE
(3)
whose data is the value of that argument. If the value argument is present, the new object must have a
value
attribute set with the
value of the argument as its value. If the defaultSelected argument is present and true, the new
object must have a selected
attribute set with no
value. If the selected argument is present and
true, the new object must have its selectedness set to true;
otherwise the fourth argument is absent or false, and the selectedness must be set
to false, even if the defaultSelected argument
is present and true.
textarea
elementautofocus
cols
disabled
form
maxlength
name
placeholder
readonly
required
rows
wrap
interface HTMLTextAreaElement : HTMLElement {
attribute boolean autofocus;
attribute unsigned long cols;
attribute boolean disabled;
readonly attribute HTMLFormElement form;
attribute long maxLength;
attribute DOMString name;
attribute DOMString placeholder;
attribute boolean readOnly;
attribute boolean required;
attribute unsigned long rows;
attribute DOMString wrap;
readonly attribute DOMString type;
attribute DOMString defaultValue;
attribute DOMString value;
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 textarea
element represents a
multiline plain text edit control for the
element's raw
value. The contents of the control represent the
control's default value.
The readonly
attribute
is a boolean attribute used to control whether the text
can be edited by the user or not.
Constraint validation: If the readonly
attribute is
specified on a textarea
element, the element is
barred from constraint validation.
A textarea
element is mutable if it is neither
disabled nor has a readonly
attribute
specified.
When a textarea
is mutable, its raw value should be
editable by the user. Any time the user causes the element's raw value to change, the
user agent must queue a task to fire a simple
event called input
at the
textarea
element, then broadcast forminput
events at the
textarea
element's form owner. 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.
A textarea
element has a dirty value flag, which must be
initially set to false, and must be set to true whenever the user
interacts with the control in a way that changes the raw value.
When the textarea
element's textContent
DOM attribute changes value, if the element's dirty value flag is false,
then the element's raw
value must be set to the value of the element's
textContent
DOM attribute.
The reset
algorithm for textarea
elements is to set the
element's value to
the value of the element's textContent
DOM
attribute.
The cols
attribute specifies the expected maximum number of characters per
line. If the cols
attribute
is specified, its value must be a valid non-negative
integer greater than zero. If applying the
rules for parsing non-negative integers to the
attribute's value results in a number greater than zero, then the
element's character
width is that value; otherwise, it is 20.
The user agent may use the textarea
element's character width as a hint to
the user as to how many characters the server prefers per line
(e.g. for visual user agents by making the width of the control be
that many characters). In visual renderings, the user agent should
wrap the user's input in the rendering so that each line is no wider
than this number of characters.
The rows
attribute specifies the number of lines to show. If the rows
attribute is specified, its
value must be a valid non-negative integer greater than
zero. If applying the rules for parsing
non-negative integers to the attribute's value results in a
number greater than zero, then the element's character height is that
value; otherwise, it is 2.
Visual user agents should set the height of the control to the number of lines given by character height.
The wrap
attribute is an enumerated attribute with two keywords
and states: the soft
keyword
which maps to the Soft state, and the
hard
keyword
which maps to the Hard state. The
missing value default is the Soft state.
If the element's wrap
attribute is in the Hard state, the cols
attribute must be
specified.
The element's value is defined to be the element's raw value with the following transformation applied:
Replace every occurrence of a U+000D CARRIAGE RETURN (CR) character not followed by a U+000A LINE FEED (LF) character, and every occurrence of a U+000A LINE FEED (LF) character not proceeded by a U+000D CARRIAGE RETURN (CR) character, by a two-character string consisting of a U+000D CARRIAGE RETURN - U+000A LINE FEED (CRLF) character pair.
If the element's wrap
attribute is in the Hard state, insert
U+000D CARRIAGE RETURN - U+000A LINE FEED (CRLF) character pairs
into the string using a UA-defined algorithm so that each line so
that each line has no more than character width
characters. The purposes of this requirement, lines are
delimited by the start of the string, the end of the string, and
U+000D CARRIAGE RETURN - U+000A LINE FEED (CRLF) character
pairs.
The maxlength
attribute is a form control maxlength
attribute controlled by the
textarea
element's dirty value flag.
If the textarea
element has a maximum allowed
value length, then the element's children must be such that
the code-point length of the value of the element's
textContent
DOM attribute is equal to or less than the
element's maximum allowed value length.
The required
attribute
is a boolean attribute. When specified, the user will
be required to enter a value before submitting the form.
Constraint validation: If the element has its
required
attribute
specified, and the element is mutable, and the element's
value is the empty string,
then the element is suffering from being missing.
The placeholder
attribute represents a hint (a word or short phrase) intended to aid
the user with data entry. A hint could be a sample value or a brief
description of the expected format. The attribute, if specified,
must have a value that contains no U+000A LINE FEED (LF) or U+000D
CARRIAGE RETURN (CR) characters.
For a longer hint or other advisory text, the title
attribute is more appropriate.
The placeholder
attribute should not be used as an alternative to a
label
.
User agents should present this hint to the user, after having stripped line breaks from it, when the element's value is the empty string and the control is not focused (e.g. by displaying it inside a blank unfocused control).
The form
attribute is used to
explicitly associate the textarea
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.
type
Returns the string "textarea
".
value
Returns the current value of the element.
Can be set, to change the value.
The cols
, placeholder
,
required
, rows
, and wrap
attributes must
reflect the respective content attributes of the same
name. The cols
and rows
attributes are limited
to only positive non-zero numbers. The maxLength
DOM
attribute must reflect the maxlength
content attribute.
The readOnly
DOM attribute must reflect the readonly
content
attribute.
The type
DOM
attribute must return the value "textarea
".
The defaultValue
DOM attribute must act like the element's textContent
DOM attribute.
The value
attribute must, on getting, return the element's raw value; on setting, it
must set the element's raw
value to the new value.
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 label
s. The select()
, selectionStart
,
selectionEnd
,
and setSelectionRange()
methods and attributes expose the element's text selection.
keygen
elementautofocus
challenge
disabled
form
keytype
name
interface HTMLKeygenElement : HTMLElement {
attribute boolean autofocus;
attribute DOMString challenge;
attribute boolean disabled;
readonly attribute HTMLFormElement form;
attribute DOMString keytype;
attribute DOMString name;
readonly attribute DOMString type;
readonly attribute boolean willValidate;
readonly attribute ValidityState validity;
readonly attribute DOMString validationMessage;
boolean checkValidity();
void setCustomValidity(in DOMString error);
readonly attribute NodeList labels;
};
The keygen
element represents a key
pair generator control. When the control's form is submitted, the
private key is stored in the local keystore, and the public key is
packaged and sent to the server.
The challenge
attribute
may be specified. Its value will be packaged with the submitted
key.
The keytype
attribute 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 listed in the cell in
the second column on the same row as the keyword.
Keyword | State |
---|---|
rsa
| RSA |
The invalid value default state is the unknown state. The missing value default state is the RSA state.
The user agent may expose a user interface for each
keygen
element to allow the user to configure settings
of the element's key pair generator, e.g. the key length.
The reset
algorithm for keygen
elements is to set these
various configuration settings back to their defaults.
The element's value is the string returned from the following algorithm:
Use the appropriate step from the following list:
keytype
attribute is in the RSA stateGenerate an RSA key pair using the settings given by the user, if appropriate.
Select an RSA signature algorithm from those listed in section 7.2.1 ("RSA Signature Algorithm") of RFC2459. [RFC2459]
keytype
attribute is in the unknown stateThe given key type is not supported. Return the empty string and abort this algorithm.
Let private key be the generated private key.
Let public key be the generated public key.
Let signature algorithm be the selected signature algorithm.
If the element has a challenge
attribute, then let
challenge be that attribute's value.
Otherwise, let challenge be the empty
string.
Let algorithm be an ASN.1 AlgorithmIdentifier
structure as defined by
RFC2459, with the algorithm
field giving the
ASN.1 OID used to identify signature
algorithm, using the OIDs defined in section 7.2 ("Signature
Algorithms") of RFC2459, and the parameters
field set up as required by RFC2459 for AlgorithmIdentifier
structures for that
algorithm. [X690] [RFC2459]
Let spki be an ASN.1 SubjectPublicKeyInfo
structure as defined by
RFC2459, with the algorithm
field set to the
algorithm structure from the previous step,
and the subjectPublicKey
field set to the
BIT STRING value resulting from ASN.1 DER encoding the public key. [X690] [RFC2459]
Let publicKeyAndChallenge be an ASN.1
PublicKeyAndChallenge
structure as defined below,
with the spki
field set to the spki structure from the previous step, and the
challenge
field set to the string challenge obtained earlier. [X690]
Let signature be the BIT STRING value resulting from ASN.1 DER encoding the signature generated by applying the signature algorithm to the byte string obtained by ASN.1 DER encoding the publicKeyAndChallenge structure, using private key as the signing key. [X690]
Let signedPublicKeyAndChallenge be an ASN.1
SignedPublicKeyAndChallenge
structure as defined
below, with the publicKeyAndChallenge
field
set to the publicKeyAndChallenge structure,
the signatureAlgorithm
field set to the algorithm structure, and the signature
field set to the BIT STRING signature from the previous step. [X690]
Return the result of base64 encoding the result of ASN.1 DER encoding the signedPublicKeyAndChallenge structure. [RFC3548] [X690]
The data objects used by the above algorithm are defined as follows. These definitions use the same "ASN.1-like" syntax defined by RFC2459. [RFC2459]
PublicKeyAndChallenge ::= SEQUENCE { spki SubjectPublicKeyInfo, challenge IA5STRING } SignedPublicKeyAndChallenge ::= SEQUENCE { publicKeyAndChallenge PublicKeyAndChallenge, signatureAlgorithm AlgorithmIdentifier, signature BIT STRING }
Constraint validation: The keygen
element is barred from constraint validation.
The form
attribute is used to
explicitly associate the keygen
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.
type
Returns the string "keygen
".
The challenge
and keytype
DOM attributes
must reflect the respective content attributes of the
same name.
The type
DOM
attribute must return the value "keygen
".
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 label
s.
This specification does not specify how the private
key generated is to be used. It is expected that after receiving the
SignedPublicKeyAndChallenge
(SPKAC) structure, the
server will generate a client certificate and offer it back to the
user for download; this certificate, once downloaded and stored in
the key store along with the private key, can then be used to
authenticate to services that use SSL and certificate
authentication.
output
elementfor
form
name
interface HTMLOutputElement : HTMLElement {
attribute DOMString htmlFor;
readonly attribute HTMLFormElement form;
attribute DOMString name;
readonly attribute DOMString type;
attribute DOMString defaultValue;
attribute DOMString value;
readonly attribute boolean willValidate;
readonly attribute ValidityState validity;
readonly attribute DOMString validationMessage;
boolean checkValidity();
void setCustomValidity(in DOMString error);
};
The output
element represents the result of a
calculation.
The for
content
attribute allows an explicit relationship to be made between the
result of a calculation and the elements that represent the values
that went into the calculation or that otherwise influenced the
calculation. The for
attribute,
if specified, must contain a string consisting of an unordered
set of unique space-separated tokens, each of which must have
the value of an ID of an element in the same
Document
.
The form
attribute is used to
explicitly associate the output
element with its
form owner. The name
attribute represents the element's name.
The element has a value mode flag which is either value or default. Initially, the value mode flag must be set to default.
When the value mode
flag is in mode default, the contents of the
element represent both the value of the element and its default
value. When the value mode
flag is in mode value, the contents of the
element represent the value of the element only, and the default
value is only accessible using the defaultValue
DOM
attribute.
The element also has a default value. Initially, the default value must be the empty string.
Whenever the element's descendants are changed in any way, if the
value mode flag is in mode
default, the element's
default value must
be set to the value of the element's textContent
DOM
attribute.
The reset
algorithm for output
elements is to set the
element's textContent
DOM attribute to the value of the
element's defaultValue
DOM attribute (thus replacing the element's child nodes), and then
to set the element's value mode
flag to default.
value
[ = value ]Returns the element's current value.
Can be set, to change the value.
defaultValue
[ = value ]Returns the element's current default value.
Can be set, to change the default value.
type
Returns the string "output
".
The value
DOM
attribute must act like the element's textContent
DOM
attribute, except that on setting, in addition, before the child
nodes are changed, the element's value mode flag must be set to value.
The defaultValue
DOM
attribute, on getting, must return the element's default value. On
setting, the attribute must set the element's default value, and, if
the element's value mode
flag is in the mode default, set the element's
textContent
DOM attribute as well.
The type
attribute must return the string "output
".
The htmlFor
DOM attribute must reflect the for
content attribute.
The willValidate
,
validity
, and validationMessage
attributes, and the checkValidity()
and
setCustomValidity()
methods, are part of the constraint validation API.
Constraint validation: output
elements are always barred from constraint
validation.
A form-associated element can have a relationship
with a form
element, which is called the element's
form owner. If a form-associated element is
not associated with a form
element, its form
owner is said to be null.
A form-associated element is, by default, associated
with its nearest ancestor form
element (as described below), but may have a form
attribute specified to
override this.
If a form-associated element has a form
attribute specified, then its
value must be the ID of a form
element in the element's
owner Document
.
When a form-associated element is created, its form owner must be initialized to null (no owner).
When a form-associated element is to be associated with a form, its form owner must be set to that form.
When a form-associated element's ancestor chain
changes, e.g. because it or one of its ancestors was inserted or
removed from a Document
, then the user agent
must reset the form owner of that element.
When a form-associated element's form
attribute is added, removed, or
has its value changed, then the user agent must reset the form
owner of that element.
When a form-associated element has a form
attribute and the ID of any of the
form
elements in the Document
changes,
then the user agent must reset the form owner of that
form-associated element.
When the user agent is to reset the form owner of a form-associated element, it must run the following steps:
If the element's form owner is not null, and
the element's form
content
attribute is not present, and the element's form owner
is one of the ancestors of the element after the change to the
ancestor chain, then do nothing, and abort these steps.
Let the element's form owner be null.
If the element has a form
content attribute, then run these substeps:
If the first element in the Document
to have
an ID that is equal to the element's form
content attribute's value is a
form
element, then associate the
form-associated element with that form
element.
Abort the "reset the form owner" steps.
Otherwise, if the form-associated element in
question has an ancestor form
element, then associate the
form-associated element with the nearest such ancestor
form
element.
Otherwise, the element is left unassociated.
In the following non-conforming snippet:
... <form id="a"> <div id="b"></div> </form> <script> document.getElementById('b').innerHTML = '<table><tr><td><form id="c"><input id="d"></table>' + '<input id="e">'; </script> ...
The form owner of "d" would be the inner nested form "c", while the form owner of "e" would be the outer form "a".
This is because despite the association of "e" with "c" in the
HTML parser, when the innerHTML
algorithm moves the nodes
from the temporary document to the "b" element, the nodes see their
ancestor chain change, and thus all the "magic" associations done
by the parser are reset to normal ancestor associations.
This example is a non-conforming document, though, as it is a
violation of the content models to nest form
elements.
form
Returns the element's form owner.
Returns null if there isn't one.
Form-associated
elements have a form
DOM attribute, which,
on getting, must return the element's form owner, or
null if there isn't one.
Constraint validation: If an element has no form owner, it is barred from constraint validation.
The name
content
attribute gives the name of the form control, as used in form
submission and in the form
element's elements
object. If the attribute
is specified, its value must not be the empty string.
Constraint validation: If an element does not
have a name
attribute specified,
or its name
attribute's value is
the empty string, then it is barred from constraint
validation.
The name
DOM
attribute must reflect the name
content attribute.
The disabled
content attribute is a boolean attribute.
A form control is disabled
if its disabled
attribute is
set, or if it is a descendant of a fieldset
element
whose disabled
attribute
is set.
A form control that is disabled must prevent any click
events that are queued on the user interaction task
source from being dispatched on the element.
Constraint validation: If an element is disabled, it is barred from constraint validation.
The disabled
DOM
attribute must reflect the disabled
content attribute.
Form controls have a value
and a checkedness. (The latter
is only used by input
elements.) These are used to
describe how the user interacts with the control.
The autofocus
content attribute allows the user to indicate that a control is to
be focused as soon as the page is loaded, allowing the user to just
start typing without having to manually focus the main control.
The autofocus
attribute is
a boolean attribute.
There must not be more than one element in the document with the
autofocus
attribute
specified.
Whenever an element with the autofocus
attribute specified is
inserted into a
document, the user agent should queue a task
that checks to see if the element is focusable, and if
so, runs the focusing steps for that element. User
agents may also change the scrolling position of the document, or
perform some other action that brings the element to the user's
attention. The task source for this task is the
DOM manipulation task source.
User agents may ignore this attribute if the user has indicated (for example, by starting to type in a form control) that he does not wish focus to be changed.
Focusing the control does not imply that the user agent must focus the browser window if it has lost focus.
The autofocus
DOM attribute must reflect the content attribute of the
same name.
In the following snippet, the text control would be focused when the document was loaded.
<input maxlength="256" name="q" value="" autofocus> <input type="submit" value="Search">
A form control maxlength
attribute, controlled by a dirty value flag declares a limit on the number of
characters a user can input.
If an element has its form
control maxlength
attribute specified,
the attribute's value must be a valid non-negative
integer. If the attribute is specified and applying the
rules for parsing non-negative integers to its value
results in a number, then that number is the element's maximum
allowed value length. If the attribute is omitted or parsing
its value results in an error, then there is no maximum
allowed value length.
Constraint validation: If an element has a maximum allowed value length, and its dirty value flag is false, and the code-point length of the element's value is greater than the element's maximum allowed value length, then the element is suffering from being too long.
User agents may prevent the user from causing the element's value to be set to a value whose code-point length is greater than the element's maximum allowed value length.
Attributes for form submission can be specified both
on form
elements and on submit button (elements that
represent buttons that submit forms, e.g. an input
element whose type
attribute is
in the Submit Button
state).
The attributes for form submission that may be
specified on form
elements are action
, enctype
, method
, novalidate
, and target
.
The corresponding attributes for form submission
that may be specified on submit
button are formaction
, formenctype
, formmethod
, formnovalidate
, and formtarget
. When omitted, they
default to the values given on the corresponding attributes on the
form
element.
The action
and
formaction
content attributes, if specified, must have a value that is a
valid URL.
The action of an element is
the value of the element's formaction
attribute, if the
element is a submit
button and has such an attribute, or the value of its
form owner's action
attribute, if it has one, or else the empty string.
The method
and
formmethod
content attributes are enumerated
attributes with the following keywords and states:
GET
, mapping
to the state GET, indicating
the HTTP GET method.POST
, mapping
to the state POST, indicating
the HTTP POST method.PUT
, mapping
to the state PUT, indicating
the HTTP PUT method.DELETE
, mapping
to the state DELETE, indicating
the HTTP DELETE method.The missing value default for these attributes is the GET state.
The method of an element is
one of those four states. If the element is a submit button and has a formmethod
attribute, then the
element's method is that
attribute's state; otherwise, it is the form owner's
method
attribute's state.
The enctype
and
formenctype
content attributes are enumerated
attributes with the following keywords and states:
application/x-www-form-urlencoded
" keyword and corresponding state.multipart/form-data
" keyword and corresponding state.text/plain
" keyword and corresponding state.The missing value default for these attributes is the
application/x-www-form-urlencoded
state.
The enctype of an element
is one of those three states. If the element is a submit button and has a formenctype
attribute, then the
element's enctype is that
attribute's state; otherwise, it is the form owner's
enctype
attribute's state.
The target
and
formtarget
content attributes, if specified, must have values that are valid browsing
context names or keywords.
The target of an element is
the value of the element's formtarget
attribute, if the
element is a submit
button and has such an attribute; or the value of its
form owner's target
attribute, if it has such an attribute; or, if one of the
child nodes of the head
element is a
base
element with a target
attribute, then the value of
the target
attribute of the
first such base
element; or, if there is no such
element, the empty string.
The novalidate
and formnovalidate
content attributes are boolean
attributes. If present, they indicate that the form is not to
be validated during submission.
The no-validate state of
an element is true if the element is a submit button and the element's
formnovalidate
attribute
is present, or if the element's form owner's novalidate
attribute is present,
and false otherwise.
The action
, method
, enctype
, and target
DOM attributes must
reflect the respective content attributes of the same
name. The noValidate
DOM
attribute must reflect the novalidate
content attribute. The
formAction
DOM
attribute must reflect the formaction
content attribute. The
formEnctype
DOM
attribute must reflect the formenctype
content attribute.
The formMethod
DOM
attribute must reflect the formmethod
content attribute. The
formNoValidate
DOM attribute must reflect the formnovalidate
content
attribute. The formTarget
DOM
attribute must reflect the formtarget
content attribute.
A listed form-associated
element is a candidate for constraint validation
unless a condition has barred the element from constraint
validation. (For example, an element is barred from
constraint validation if it is an output
or
fieldset
element.)
An element can have a custom validity error message
defined. Initially, an element must have its custom validity
error message set to the empty string. When its value is not
the empty string, the element is suffering from a custom
error. It can be set using the setCustomValidity()
method. The user agent should use the custom validity error
message when alerting the user to the problem with the
control.
An element can be constrained in various ways. The following is the list of validity states that a form control can be in, making the control invalid for the purposes of constraint validation. (The definitions below are non-normative; other parts of this specification define more precisely when each state applies or does not.)
When a control has no value but has a required
attribute (input
required
, textarea
required
).
When a control that allows arbitrary user input has a value that is not in the correct syntax (E-mail, URL).
When a control has a value that doesn't satisfy the
pattern
attribute.
When a control has a value that is too long for the
form control maxlength
attribute (input
maxlength
,
textarea
maxlength
).
When a control has a value that is too low for the min
attribute.
When a control has a value that is too high for the
max
attribute.
When a control has a value that doesn't fit the rules
given by the step
attribute.
When a control's custom validity error
message (as set by the element's setCustomValidity()
method) is not the empty string.
An element can still suffer from these states even when the element is disabled; thus these states can be represented in the DOM even if validating the form during submission wouldn't indicate a problem to the user.
An element satisfies its constraints if it is not suffering from any of the above validity states.
When the user agent is required to statically validate the
constraints of form
element form, it must run the following steps, which return
either a positive result (all the controls in the form are
valid) or a negative result (there are invalid controls)
along with a (possibly empty) list of elements that are invalid and
for which no script has claimed responsibility:
Let controls be a list of all the submittable elements whose form owner is form, in tree order.
Let invalid controls be an initially empty list of elements.
For each element field in controls, in tree order, run the following substeps:
If field is not a candidate for constraint validation, then move on to the next element.
Otherwise, if field satisfies its constraints, then move on to the next element.
Otherwise, add field to invalid controls.
If invalid controls is empty, then return a positive result and abort these steps.
Let unhandled invalid controls be an initially empty list of elements.
For each element field in invalid controls, if any, in tree order, run the following substeps:
Fire a simple event named invalid
at field.
If the event was not canceled, then add field to unhandled invalid controls.
Return a negative result with the list of elements in the unhandled invalid controls list.
If a user agent is to interactively validate the
constraints of form
element form, then the user agent must run the following
steps:
Statically validate the constraints of form, and let unhandled invalid controls be the list of elements returned if the result was negative.
If the result was positive, then return that result and abort these steps.
Report the problems with the constraints of at least one of
the elements given in unhandled invalid
controls to the user. User agents may focus one of those
elements in the process, by running the focusing steps
for that element, and may change the scrolling position of the
document, or perform some other action that brings the element to
the user's attention. User agents may report more than one
constraint violation. User agents may coalesce related constraint
violation reports if appropriate (e.g. if multiple radio buttons in
a group are marked as
required, only one error need be reported). If one of the controls
is not visible to the user (e.g. it has the hidden
attribute set) then user agents
may report a script error.
Return a negative result.
willValidate
Returns true if the element will be validated when the form is submitted; false otherwise.
setCustomValidity
(message)Sets a custom error, so that the element would fail to validate. The given message is the message to be shown to the user when reporting the problem to the user.
If the argument is the empty string, clears the custom error.
validity
. valueMissing
Returns true if the element has no value but is a required field; false otherwise.
validity
. typeMismatch
Returns true if the element's value is not in the correct syntax; false otherwise.
validity
. patternMismatch
Returns true if the element's value doesn't match the provided pattern; false otherwise.
validity
. tooLong
Returns true if the element's value is longer than the provided maximum length; false otherwise.
validity
. rangeUnderflow
Returns true if the element's value is lower than the provided minimum; false otherwise.
validity
. rangeOverflow
Returns true if the element's value is higher than the provided maximum; false otherwise.
validity
. stepMismatch
Returns true if the element's value doesn't fit the rules given by the step
attribute; false otherwise.
validity
. customError
Returns true if the element has a custom error; false otherwise.
validity
. valid
Returns true if the element's value has no validity problems; false otherwise.
checkValidity
()Returns true if the element's value has no validity problems;
false otherwise. Fires an invalid
event at the element in the
latter case.
validationMessage
Returns the error message that would be shown to the user if the element was to be checked for validity.
The willValidate
attribute must return true if an element is a candidate for
constraint validation, and false otherwise (i.e. false if any
conditions are barring it from constraint validation).
The setCustomValidity(message)
, when invoked, must set the
custom validity error message to the value of the given
message argument.
The validity
attribute must return a ValidityState
object that
represents the validity states of the element. This
object is live, and the same object must be returned each time the
element's validity
attribute
is retrieved.
interface ValidityState { readonly attribute boolean valueMissing; readonly attribute boolean typeMismatch; readonly attribute boolean patternMismatch; readonly attribute boolean tooLong; readonly attribute boolean rangeUnderflow; readonly attribute boolean rangeOverflow; readonly attribute boolean stepMismatch; readonly attribute boolean customError; readonly attribute boolean valid; };
A ValidityState
object has the following
attributes. On getting, they must return true if the corresponding
condition given in the following list is true, and false
otherwise.
valueMissing
The control is suffering from being missing.
typeMismatch
The control is suffering from a type mismatch.
patternMismatch
The control is suffering from a pattern mismatch.
tooLong
The control is suffering from being too long.
rangeUnderflow
The control is suffering from an underflow.
rangeOverflow
The control is suffering from an overflow.
stepMismatch
The control is suffering from a step mismatch.
customError
The control is suffering from a custom error.
valid
None of the other conditions are true.
When the checkValidity()
method is invoked, if the element is a candidate for
constraint validation and does not satisfy its constraints, the user
agent must fire a simple event named invalid
at the element and return
false. Otherwise, it must only return true without doing anything
else.
The validationMessage
attribute must return the empty string if the element is not a
candidate for constraint validation or if it is one but
it satisfies its constraints;
otherwise, it must return a suitably localized message that the user
agent would show the user if this were the only form with a validity
constraint problem. If the element is suffering from a custom
error, then the custom validity error message
should be present in the return value.
Servers should not rely on client-side validation. Client-side validation can be intentionally bypassed by hostile users, and unintentionally bypassed by users of older user agents or automated tools that do not implement these features. The constraint validation features are only intended to improve the user experience, not to provide any kind of security mechanism.
This section is non-normative.
...
User agents may establish a button in each form as being the
form's default button. This should be the first submit button in tree
order whose form owner is that form
element, but user agents may pick another button if another would be
more appropriate for the platform. If the platform supports letting
the user submit a form implicitly (for example, on some platforms
hitting the "enter" key while a text field is focused implicitly
submits the form), then doing so must cause the form's default
button's activation behavior, if any, to be
run.
Consequently, if the default button is disabled, the form is not submitted when such an implicit submission mechanism is used. (A button has no activation behavior when disabled.)
If the form has no submit
button, then the implicit submission mechanism must just
submit the
form
element from the form
element
itself.
When a form form is submitted from an element submitter (typically a button), the user agent must run the following steps:
If form is in
a Document
that has no associated browsing
context or whose browsing context has its
sandboxed forms browsing context flag set, then abort
these steps without doing anything.
If form is already being submitted
(i.e. the form was submitted again while processing
the events fired from the next two steps, probably from a script
redundantly calling the submit()
method on form), then abort these steps. This doesn't affect
the earlier instance of this algorithm.
If the submitter is anything but a
form
element, and the submitter
element's no-validate
state is false, then interactively validate the
constraints of form and examine the
result: if the result is negative (the constraint validation
concluded that there were invalid fields and probably informed the
user of this) then abort these steps.
If the submitter is anything but a
form
element, then fire a simple event
that bubbles, named submit
, at form. If
the event's default action is prevented (i.e. if the event is
canceled) then abort these steps. Otherwise, continue (effectively
the default action is to perform the submission).
Let controls be a list of all the submittable elements whose form owner is form, in tree order.
Let the form data set be a list of name-value-type tuples, initially empty.
Constructing the form data set. For each element field in controls, in tree order, run the following substeps:
If any of the following conditions are met, then skip these substeps for this element:
datalist
element ancestor.input
element whose type
attribute is in the Checkbox state and
whose checkedness is
false.input
element whose type
attribute is in the Radio Button state and
whose checkedness is
false.input
element whose type
attribute is in the File Upload state but
the control does not have any files selected.object
element that is not using a
plugin.Otherwise, process field as follows:
Let type be the value of the type
DOM attribute of field.
If the field element is an
input
element whose type
attribute is in the Image Button state,
then run these further nested substeps:
If the field element has an name
attribute specified and value
is not the empty string, let name be that
value followed by a single U+002E FULL STOP (.)
character. Otherwise, let name be the empty
string.
Let namex be the string consisting of the concatenation of name and a single U+0078 LATIN SMALL LETTER X (x) character.
Let namey be the string consisting of the concatenation of name and a single U+0079 LATIN SMALL LETTER Y (y) character.
The field element is submitter, and before this algorithm was invoked the user indicated a coordinate. Let x be the x-component of the coordinate selected by the user, and let y be the y-component of the coordinate selected by the user.
Append an entry in the form data set with the name namex, the value x, and the type type.
Append an entry in the form data set with the name namey and the value y, and the type type.
Skip the remaining substeps for this element: if there are any more elements in controls, return to the top of the constructing the form data set step, otherwise, jump to the next step in the overall form submission algorithm.
If the field element does not have a
name
attribute specified, or
its name
attribute's value is
the empty string, skip these substeps for this element: if there
are any more elements in controls, return to
the top of the constructing
the form data set step, otherwise, jump to the next step in
the overall form submission algorithm.
Let name be the value of the field element's name
attribute.
If the field element is a
select
element, then for each option
element in the select
element whose selectedness is true,
append an entry in the form data set with the
name as the name, the value of the
option
element as the value, and type as the type.
Otherwise, if the field element is an
input
element whose type
attribute is in the Checkbox state or the
Radio Button state,
then run these further nested substeps:
If the field element has a value
attribute specified, then
let value be the value of that attribute;
otherwise, let value be the string
"on
".
Append an entry in the form data set with name as the name, value as the value, and type as the type.
Otherwise, if the field element is an
input
element whose type
attribute is in the File Upload state, then for
each file selected in the
input
element, append an entry in the form data set with the name as
the name, the file (consisting of the name, the type, and the
body) as the value, and type as the
type.
Otherwise, if the field element is an
object
element: try to obtain a form submission
value from the plugin,
and if that is successful, append an entry in the form data set with name as the
name, the returned form submission value as the value, and the
string "object
" as the type.
Otherwise, append an entry in the form data set with name as the name, the value of the field element as the value, and type as the type.
Let action be the submitter element's action.
If action is the empty string, let action be the document's address.
This step is a willful violation of RFC 3986. [RFC3986]
Resolve the URL action, relative to the submitter element. If this fails, abort these steps. Otherwise, let action be the resulting absolute URL.
Let scheme be the <scheme> of the resulting absolute URL.
Let enctype be the submitter element's enctype.
Let method be the submitter element's method.
Let target be the submitter element's target.
Select the appropriate row in the table below based on the value of scheme as given by the first cell of each row. Then, select the appropriate cell on that row based on the value of method as given in the first cell of each column. Then, jump to the steps named in that cell and defined below the table.
If scheme is not one of those listed in this table, then the behavior is not defined by this specification. User agents should, in the absence of another specification defining this, act in a manner analogous to that defined in this specification for similar schemes.
The behaviors are as follows:
Let query be the result of encoding the
form data set using the application/x-www-form-urlencoded
encoding
algorithm, interpreted as a US-ASCII string.
Let destination be a new URL that is equal to the action except that its <query> component is replaced by query (adding a U+003F QUESTION MARK (?) character if appropriate).
Let target browsing context be the form submission target browsing context.
Navigate target browsing context to destination. If target browsing context was newly created for this purpose by the steps above, then it must be navigated with replacement enabled.
Let entity body be the result of encoding the form data set using the appropriate form encoding algorithm.
Let target browsing context be the form submission target browsing context.
Let MIME type be determined as follows:
application/x-www-form-urlencoded
application/x-www-form-urlencoded
".multipart/form-data
multipart/form-data
".text/plain
text/plain
".Navigate target browsing context to action using the HTTP method given by method and with entity body as the entity body, of type MIME type. If target browsing context was newly created for this purpose by the steps above, then it must be navigated with replacement enabled.
Let target browsing context be the form submission target browsing context.
Navigate target browsing context to action using the DELETE method. If target browsing context was newly created for this purpose by the steps above, then it must be navigated with replacement enabled.
Let target browsing context be the form submission target browsing context.
Navigate target browsing context to action. If target browsing context was newly created for this purpose by the steps above, then it must be navigated with replacement enabled.
Let data be the result of encoding the form data set using the appropriate form encoding algorithm.
If action contains the string "%%%%
" (four U+0025 PERCENT SIGN characters),
then %-escape all bytes in data that, if
interpreted as US-ASCII, do not match the unreserved
production in the URI Generic Syntax,
and then, treating the result as a US-ASCII string, further
%-escape all the U+0025 PERCENT SIGN characters in the resulting
string and replace the first occurrence of "%%%%
" in action with the
resulting double-escaped string. [RFC3986]
Otherwise, if action contains the string
"%%
" (two U+0025 PERCENT SIGN characters
in a row, but not four), then %-escape all characters in data that, if interpreted as US-ASCII, do not
match the unreserved
production in the URI
Generic Syntax, and then, treating the result as a US-ASCII
string, replace the first occurrence of "%%
" in action with the
resulting escaped string. [RFC3986]
Let target browsing context be the form submission target browsing context.
Navigate target browsing context to the potentially modified action. If target browsing context was newly created for this purpose by the steps above, then it must be navigated with replacement enabled.
Let data be the result of encoding the form data set using the appropriate form encoding algorithm.
Let MIME type be determined as follows:
application/x-www-form-urlencoded
application/x-www-form-urlencoded
".multipart/form-data
multipart/form-data
".text/plain
text/plain
".Let destination be the result of concatenating the following:
data:
".;base64,
".Let target browsing context be the form submission target browsing context.
Navigate target browsing context to destination. If target browsing context was newly created for this purpose by the steps above, then it must be navigated with replacement enabled.
Let headers be the resulting encoding the
form data set using the application/x-www-form-urlencoded
encoding
algorithm, interpreted as a US-ASCII string.
Replace occurrences of U+002B PLUS SIGN characters (+) in
headers with the string "%20
".
Let destination consist of all the characters from the first character in action to the character immediately before the first U+003F QUESTION MARK character (?), if any, or the end of the string if there are none.
Append a single U+003F QUESTION MARK character (?) to destination.
Append headers to destination.
Let target browsing context be the form submission target browsing context.
Navigate target browsing context to destination. If target browsing context was newly created for this purpose by the steps above, then it must be navigated with replacement enabled.
Let body be the resulting encoding the
form data set using the appropriate
form encoding algorithm and then %-escaping all the bytes
in the resulting byte string that, when interpreted as US-ASCII,
do not match the unreserved
production in
the URI Generic Syntax. [RFC3986]
Let destination have the same value as action.
If destination does not contain a U+003F QUESTION MARK character (?), append a single U+003F QUESTION MARK character (?) to destination. Otherwise, append a single U+0026 AMPERSAND character (&).
Append the string "body=
" to destination.
Append body, interpreted as a US-ASCII string, to destination.
Let target browsing context be the form submission target browsing context.
Navigate target browsing context to destination. If target browsing context was newly created for this purpose by the steps above, then it must be navigated with replacement enabled.
The form submission target browsing context is obtained, when needed by the behaviors described above, as follows: If the user indicated a specific browsing context to use when submitting the form, then that is the target browsing context. Otherwise, apply the rules for choosing a browsing context given a browsing context name using target as the name and the browsing context of form as the context in which the algorithm is executed; the resulting browsing context is the target browsing context.
The appropriate form encoding algorithm is determined as follows:
application/x-www-form-urlencoded
application/x-www-form-urlencoded
encoding
algorithm.multipart/form-data
multipart/form-data
encoding
algorithm.text/plain
text/plain
encoding
algorithm.The application/x-www-form-urlencoded
encoding
algorithm is as follows:
Let result be the empty string.
If the form
element has an accept-charset
attribute,
then, taking into account the characters found in the form data set's names and values, and the character
encodings supported by the user agent, select a character encoding
from the list given in the form
's accept-charset
attribute
that is an ASCII-compatible character encoding. If
none of the encodings are supported, then let the selected
character encoding be UTF-8.
Otherwise, if the document's character encoding is an ASCII-compatible character encoding, then that is the selected character encoding.
Otherwise, let the selected character encoding be UTF-8.
Let charset be the preferred MIME name of the selected character encoding.
If the entry's name is "_charset_
" and
its type is "hidden
", replace its value with
charset.
If the entry's type is "file
", replace
its value with the file's filename only.
For each entry in the form data set, perform these substeps:
For each character in the entry's name and value that cannot be expressed using the selected character encoding, replace the character by a string consisting of a U+0026 AMPERSAND character (&), one of more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) representing the Unicode code point of the character in base ten, and finally a U+003B SEMICOLON character (;).
For each character in the entry's name and value, apply the following subsubsteps:
If the character isn't in the range U+0020, U+002A, U+002D, U+002E, U+0030 .. U+0039, U+0041 .. U+005A, U+005F, U+0061 .. U+007A then replace the character with a string formed as follows: Start with the empty string, and then, taking each byte of the character when expressed in the selected character encoding in turn, append to the string a U+0025 PERCENT SIGN character (%) followed by two characters in the ranges U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) and U+0041 LATIN CAPITAL LETTER A to U+005A LATIN CAPITAL LETTER Z representing the hexadecimal value of the byte (zero-padded if necessary).
If the character is a U+0020 SPACE character, replace it with a single U+002B PLUS SIGN character (+).
If the entry's name is "isindex
",
its type is "text
", and this is the first
entry in the form data set, then append the
value to result and skip the rest of the
substeps for this entry, moving on to the next entry, if any, or
the next step in the overall algorithm otherwise.
If this is not the first entry, append a single U+0026 AMPERSAND character (&) to result.
Append the entry's name to result.
Append a single U+003D EQUALS SIGN character (=) to result.
Append the entry's value to result.
Encode result as US-ASCII and return the resulting byte stream.
The multipart/form-data
encoding
algorithm is to encode the form data set
using the rules described by RFC2388, Returning Values from
Forms: multipart/form-data
, and return
the resulting byte stream. [RFC2388]
Each entry in the form data set is a field, the name of the entry is the field name and the value of the entry is the field value.
The order of parts must be the same as the order of fields in the form data set. Multiple entries with the same name must be treated as distinct fields.
The text/plain
encoding
algorithm is as follows:
Let result be the empty string.
If the form
element has an accept-charset
attribute,
then, taking into account the characters found in the form data set's names and values, and the character
encodings supported by the user agent, select a character encoding
from the list given in the form
's accept-charset
attribute. If none of the encodings are supported, then let the
selected character encoding be UTF-8.
Otherwise, the selected character encoding is the document's character encoding.
Let charset be the preferred MIME name of the selected character encoding.
If the entry's name is "_charset_
" and
its type is "hidden
", replace its value with
charset.
If the entry's type is "file
", replace
its value with the file's filename only.
For each entry in the form data set, perform these substeps:
Append the entry's name to result.
Append a single U+003D EQUALS SIGN character (=) to result.
Append the entry's value to result.
Append a U+000D CARRIAGE RETURN (CR) U+000A LINE FEED (LF) character pair to result.
Encode result using the selected character encoding and return the resulting byte stream.
When a form form is reset, the user agent must invoke
the reset algorithm
of each resettable elements
whose form owner is form, and must
then broadcast formchange
events from form.
Each resettable element
defines its own reset
algorithm. Changes made to form controls as part of these
algorithms do not count as changes caused by the user (and thus,
e.g., do not cause input
events to
fire).
When the user agent is to broadcast forminput
events or
broadcast formchange
events from a form
element form, it must run the following steps:
Let controls be a list of all the resettable elements whose form owner is form.
forminput
events, let event name be forminput
. Otherwise the user agent
was to broadcast formchange
events; let event name be formchange
.For each element in controls, in tree order, fire a simple event named event name at the element.