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 coordinates represent the position relative to the edge of the image, with the coordinate space having the positive x direction to the right, and the positive y direction downwards.
The x-component must be a valid integer representing a number x in the range −(borderleft+paddingleft) ≤ x ≤ width+borderright+paddingright, where width is the rendered width of the image, borderleft is the width of the border on the left of the image, paddingleft is the width of the padding on the left of the image, borderright is the width of the border on the right of the image, and paddingright is the width of the padding on the right of the image, with all dimensions given in CSS pixels.
The y-component must be a valid integer representing a number y in the range −(bordertop+paddingtop) ≤ y ≤ height+borderbottom+paddingbottom, where height is the rendered height of the image, bordertop is the width of the border above the image, paddingtop is the width of the padding above the image, borderbottom is the width of the border below the image, and paddingbottom is the width of the padding below the image, with all dimensions given in CSS pixels.
Where a border or padding is missing, its width is zero CSS pixels.
The formaction, formenctype, formmethod, formnovalidate, and formtarget attributes are attributes
for form submission.
The following common input element content
attributes and IDL attributes apply to the element:
alt,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
src, and
width content attributes;
value IDL attribute.
The value IDL 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 IDL attributes and methods do not apply to the
element:
checked,
files,
list,
selectedOption,
selectionStart,
selectionEnd,
valueAsDate, and
valueAsNumber IDL 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 IDL 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 IDL attributes and methods do not apply to the
element:
checked,
files,
list,
selectedOption,
selectionStart,
selectionEnd,
valueAsDate, and
valueAsNumber IDL 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 IDL 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 IDL attributes and methods do not apply to the
element:
checked,
files,
list,
selectedOption,
selectionStart,
selectionEnd,
valueAsDate, and
valueAsNumber IDL 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, regardless of the
requirements and definitions below.
autocomplete attributeUser agents sometimes have features for helping users fill forms in, for example prefilling the user's address based on earlier user input.
The 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 either that the control's input data is particularly sensitive (for example the activation code for a nuclear weapon); or that it 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; or that the document provides its own autocomplete mechanism and does not want the user agent to provide autocompletion values.
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. (By default, the autocomplete attribute of
form elements is in the on state.)
Each input element has a resulting
autocompletion state, which is either on or off.
When an input element is in one of the following
conditions, the input element's resulting
autocompletion state is on; otherwise, the
input element's resulting autocompletion
state is off:
autocomplete
attribute is in the on state.autocomplete
attribute is in the default state,
and the element has no form owner.autocomplete
attribute is in the default state,
and the element's form owner's autocomplete attribute is in
the on
state.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, and should not offer past
values to the user.
In addition, if the resulting autocompletion state is off, values are reset when traversing the history.
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><label>Account: <input type="text" name="ac" autocomplete="off"></label></p> <p><label>PIN: <input type="password" name="pin" autocomplete="off"></label></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.
This URL field offers some suggestions.
<label>Homepage: <input name=hp type=url list=hpurls></label> <datalist id=hpurls> <option value="http://www.google.com/" label="Google"> <option value="http://www.reddit.com/" label="Reddit"> </datalist>
Other URLs from the user's history might show also; this is up to the user agent.
This example demonstrates how to design a form that uses the autocompletion list feature while still degrading usefully in legacy user agents.
If the autocompletion list is merely an aid, and is not
important to the content, then simply using a datalist
element with children option elements is enough. To
prevent the values from being rendered in legacy user agents, they
should be placed inside the value attribute instead of
inline.
<p> <label> Enter a breed: <input type="text" name="breed" list="breeds"> <datalist id="breeds"> <option value="Abyssinian"> <option value="Alpaca"> <!-- ... --> </datalist> </label> </p>
However, if the values need to be shown in legacy UAs, then
fallback content can be placed inside the datalist
element, as follows:
<p>
<label>
Enter a breed:
<input type="text" name="breed" list="breeds">
</label>
<datalist id="breeds">
<label>
or select one from the list:
<select name="breed">
<option value=""> (none selected)
<option>Abyssinian
<option>Alpaca
<!-- ... -->
</select>
</label>
</datalist>
</p>
The fallback content will only be shown in UAs that don't
support datalist. The options, on the other hand, will
be detected by all UAs, even though they are not direct children of
the datalist element.
Note that if an option element used in a
datalist is selected, it will be selected
by default by legacy UAs (because it affects the
select), but it will not have any effect on the
input element in UAs that support
datalist.
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.
In the following example, the existing product identifiers cannot be modified, but they are still displayed as part of the form, for consistency with the row representing a new product (where the identifier is not yet filled in).
<form action="products.cgi" method=post enctype="multipart/form-data"> <table> <tr> <th> Product ID <th> Product name <th> Price <th> Action <tr> <td> <input readonly name="1.pid" value="H412"> <td> <input required name="1.pname" value="Floor lamp Ulke"> <td> $<input required type=number min=0 step=0.01 name="1.pprice" value="49.99"> <td> <button formnovalidate name="action" value="delete:1">Delete</button> <tr> <td> <input readonly name="2.pid" value="FG28"> <td> <input required name="2.pname" value="Table lamp Ulke"> <td> $<input required type=number min=0 step=0.01 name="2.pprice" value="24.99"> <td> <button formnovalidate name="action" value="delete:2">Delete</button> <tr> <td> <input required name="3.pid" value="" pattern="[A-Z0-9]+"> <td> <input required name="3.pname" value=""> <td> $<input required type=number min=0 step=0.01 name="3.pprice" value=""> <td> <button formnovalidate name="action" value="delete:3">Delete</button> </table> <p> <button formnovalidate name="action" value="add">Add</button> </p> <p> <button name="action" value="update">Save</button> </p> </form>
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 IDL attribute is
limited to only non-negative numbers greater than
zero.
required attributeThe required
attribute is a boolean attribute. When specified, the
element is required.
Constraint validation: If the element is required, and its value IDL 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.
The following form has two required fields, one for an e-mail address and one for a password. It also has a third field that is only considerd valid if the user types the same password in the password field and this third field.
<h1>Create new account</h1> <form action="/newaccount" method=post> <p> <label for="username">E-mail address:</label> <input id="username" type=email required name=un> <p> <label for="password1">Password:</label> <input id="password1" type=password required name=up> <p> <label for="password2">Confirm password:</label> <input id="password2" type=password onforminput="setCustomValidity(value != password1.value ? 'Passwords do not match.' : '')"> <p> <input type=submit value="Create account"> </form>
multiple attributeThe multiple
attribute is a boolean attribute that indicates whether
the user is to be allowed to specify more than one value.
The following extract shows how an e-mail client's "Cc" field could accept multiple e-mail addresses.
<label>Cc: <input type=email multiple name=cc></label>
If the user had, amongst many friends in his user contacts database, two friends "Arthur Dent" (with address "art@example.net") and "Adam Josh" (with address "adamjosh@example.net"), then, after the user has typed "a", the user agent might suggest these two e-mail addresses to the user.

The page could also link in the user's contacts database from the site:
<label>Cc: <input type=email multiple name=cc list=contacts></label> ... <datalist id="contacts"> <option value="hedral@damowmow.com"> <option value="pillar@example.com"> <option value="astrophy@cute.example"> <option value="astronomy@science.example.org"> </datalist>
Suppose the user had entered "bob@example.net" into this text
field, and then started typing a second e-mail address starting
with "a". The user agent might show both the two friends mentioned
earlier, as well as the "astrophy" and "astronomy" values given in
the datalist element.

The following extract shows how an e-mail client's "Attachments" field could accept multiple files for upload.
<label>Attachments: <input type=file multiple name=att></label>
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.
The following extract shows how a messaging client's text entry could be arbitrarily restricted to a fixed number of characters, thus forcing any conversion through this medium to be terse and discouraging intelligent discourse.
What are you doing? <input name=status maxlength=140>
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 5, 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:
A 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 titles 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.
The following date control limits input to dates that are before the 1980s:
<input name=bday type=date max="1979-12-31">
The following number control limits input to whole numbers greater than zero:
<input name=quantity required type=number min=1 value=1>
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.
The following range control only accepts values in the range 0..1, and allows 256 steps in that range:
<input name=opacity type=range min=0 max=1 step=0.00392156863>
The following control allows any time in the day to be selected, with any accuracy (e.g. thousandth-of-a-second accuracy or more):
<input name=favtime type=time step=any>
Normally, time controls are limited to an accuracy of one minute.
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_STATE_ERR exception if it is
set to any value other than the empty string when the control is a
file upload control.
checked [ = value ]Returns the current checkedness of the form control.
Can be set, to change the checkedness.
filesReturns a FileList object listing the selected files of
the form control.
Throws an INVALID_STATE_ERR exception if the
control isn't a file control.
valueAsDate [ = value ]Returns a Date object representing the form
control's value, if
applicable; otherwise, returns null.
Can be set, to change the value.
Throws an INVALID_STATE_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_STATE_ERR exception if the
control is neither date- or time-based nor numeric.
stepUp( [ n ] )stepDown( [ n ] )Changes the form control's value by the value given in the
step attribute, multiplied by
n. The default is 1.
Throws INVALID_STATE_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 by the given amount would take the
value out of range.
listReturns the datalist element indicated by the
list attribute.
selectedOptionReturns the option element from the
datalist element indicated by the list attribute that matches the
form control's value.
The value IDL
attribute allows scripts to manipulate the value of an input
element. The attribute is in one of the following modes, which
define its behavior:
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, if the
new value is the empty string, it must empty the list of selected files;
otherwise, it must throw an INVALID_STATE_ERR
exception.The checked IDL
attribute allows scripts to manipulate the checkedness of an
input element. On getting, it must return the current
checkedness of the element;
and on setting, it must set the element's checkedness to the new value and
set the element's dirty checkedness
flag to true.
The files IDL
attribute allows scripts to access the element's selected files. On
getting, if the IDL attribute applies, it must return a
FileList object that represents the current selected files. The
same object must be returned until the list of selected files
changes. If the IDL attribute does not apply, then it must instead
throw an INVALID_STATE_ERR exception. [FILEAPI]
The valueAsDate IDL
attribute represents the value of the element, interpreted
as a date.
On getting, if the valueAsDate attribute does not
apply, as defined for the input element's type attribute's current state, then
return null. Otherwise, run the algorithm to convert a
string to a Date object defined for that state;
if the algorithm returned a Date object, then return
it, otherwise, return null.
On setting, if the valueAsDate attribute does not
apply, as defined for the input element's type attribute's current state, then
throw an INVALID_STATE_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 IDL
attribute represents the value
of the element, interpreted as a number.
On getting, if the valueAsNumber attribute does
not apply, as defined for the input element's type attribute's current state, then
return a Not-a-Number (NaN) value. Otherwise, if the valueAsDate
attribute applies, run the algorithm to convert a
string to a Date object defined for that state;
if the algorithm returned a Date object, then return
the time value of the object (the number of milliseconds from
midnight UTC the morning of 1970-01-01 to the time represented by
the Date object), otherwise, return a Not-a-Number
(NaN) value. Otherwise, run the algorithm to convert a
string to a number defined for that state; if the algorithm
returned a number, then return it, otherwise, return a Not-a-Number
(NaN) value.
On setting, if the valueAsNumber attribute does
not apply, as defined for the input element's type attribute's current state, then
throw an INVALID_STATE_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(n) and stepUp(n) methods, when invoked, must run the
following algorithm:
If the stepDown() and
stepUp() methods do not
apply, as defined for the input element's type attribute's current state, then
throw an INVALID_STATE_ERR exception, and abort these
steps.
If the element has no allowed value step, then throw an
INVALID_STATE_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_STATE_ERR exception, and abort
these steps; otherwise, let value be the result
of that algorithm.
Let n be the argument, or 1 if the argument was omitted.
Let delta be the allowed value step multiplied by n.
If the method invoked was the stepDown() method, negate delta.
Let value be the result of adding delta to value.
If the element has a minimum, and the value is less than that minimum, then throw a
INVALID_STATE_ERR exception.
If the element has a maximum, and the value is greater than that maximum, then throw a
INVALID_STATE_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 IDL
attribute must return the current suggestions source element, if
any, or null otherwise.
The selectedOption
IDL 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 that
bubbles named 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 that bubbles named 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 that bubbles named 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 that bubbles named 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 tasks is the user interaction task source.
button elementautofocusdisabledformformactionformenctypeformmethodformnovalidateformtargetnametypevalueinterface 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.
Constraint validation: If the type attribute is in the Reset Button state or
the Button state,
the element is barred from constraint validation.
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 formnovalidate attribute can
be used to make submit buttons that do not trigger the constraint
validation.
The formaction, formenctype, formmethod, formnovalidate, and formtarget must not be specified
if the element's type
attribute is not in the Submit Button
state.
The value
attribute gives the element's value for the purposes of form
submission. 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 IDL 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 labels.
The following button is labeled "Show hint" and pops up a dialog box when activated:
<button type=button
onclick="alert('This 15-20 minute piece was composed by George Gershwin.')">
Show hint
</button>
select elementoption or optgroup elements.autofocusdisabledformmultiplenamesizeinterface HTMLSelectElement : HTMLElement {
attribute boolean autofocus;
attribute boolean disabled;
readonly attribute HTMLFormElement form;
attribute boolean multiple;
attribute DOMString name;
attribute unsigned long size;
readonly attribute DOMString type;
readonly attribute HTMLOptionsCollection options;
attribute unsigned long length;
caller getter any item(in unsigned long index);
caller getter any namedItem(in DOMString name);
void add(in HTMLElement element, in optional 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 that bubbles named
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 that
bubbles named 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.
typeReturns "select-multiple" if the element
has a multiple
attribute, and "select-one"
otherwise.
optionsReturns 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.
selectedOptionsReturns 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 IDL
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
IDL 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 IDL
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
IDL 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
IDL 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 IDL
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 IDL
attributes must reflect the respective content
attributes of the same name. The size IDL attribute limited to
only non-negative numbers greater than zero.
The willValidate, validity, and validationMessage
attributes, and the checkValidity() and setCustomValidity()
methods, are part of the constraint validation API. The
labels attribute provides a list
of the element's labels.
The following example shows how a select element
can be used to offer the user with a set of options from which the
user can select a single option. The default option is
preselected.
<p> <label for="unittype">Select unit type:</label> <select id="unittype" name="unittype"> <option value="1"> Miner </option> <option value="2"> Puffer </option> <option value="3" selected> Snipey </option> <option value="4"> Max </option> <option value="5"> Firebot </option> </select> </p>
Here, the user is offered a set of options from which he can select any number. By default, all five options are selected.
<p> <label for="allowedunits">Select unit types to enable on this map:</label> <select id="allowedunits" name="allowedunits" multiple> <option value="1" selected> Miner </option> <option value="2" selected> Puffer </option> <option value="3" selected> Snipey </option> <option value="4" selected> Max </option> <option value="5" selected> Firebot </option> </select> </p>
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.
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.
optionsReturns an HTMLCollection of the options elements of the table.
The options
IDL 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.disabledlabelinterface 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.
The following snippet shows how a set of lessons from three
courses could be offered in a select drop-down
widget:
<form action="courseselector.dll" method="get">
<p>Which course would you like to watch today?
<p><label>Course:
<select name="c">
<optgroup label="8.01 Physics I: Classical Mechanics">
<option value="8.01.1">Lecture 01: Powers of Ten
<option value="8.01.2">Lecture 02: 1D Kinematics
<option value="8.01.3">Lecture 03: Vectors
<optgroup label="8.02 Electricity and Magnestism">
<option value="8.02.1">Lecture 01: What holds our world together?
<option value="8.02.2">Lecture 02: Electric Field
<option value="8.02.3">Lecture 03: Electric Flux
<optgroup label="8.03 Physics III: Vibrations and Waves">
<option value="8.03.1">Lecture 01: Periodic Phenomenon
<option value="8.03.2">Lecture 02: Beats
<option value="8.03.3">Lecture 03: Forced Oscillations with Damping
</select>
</label>
<p><input type=submit value="▶ Play">
</form>
option elementselect element.datalist element.optgroup element.disabledlabelselectedvalue[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;
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. Except where 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 three or fewer 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). The fourth argument can be used to explicitly set the
initial selectedness state when
using the constructor.
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.
selectedReturns true if the element is selected, and false otherwise.
indexReturns the index of the element in its select
element's options
list.
formReturns the element's form element, if any, or
null otherwise.
textSame as textContent.
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
and label IDL
attributes must reflect the respective content
attributes of the same name. The defaultSelected
IDL attribute must reflect the selected content attribute.
The value IDL
attribute, on getting, must return the value of the element's value content attribute, if it has
one, or else the value of the element's textContent IDL
attribute. On setting, the element's value content attribute must be set
to the new value.
The selected
IDL attribute must return true if the element's selectedness is true, and
false otherwise.
The index IDL
attribute must return the element's index.
The text IDL
attribute, on getting, must return the same value as the
textContent IDL attribute on the element, and on
setting, must act as if the textContent IDL attribute
on the element had been set to the new value.
The form IDL
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 IDL
attribute must return the same value as the form IDL 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. The element's document must be the active
document of the browsing context of the
Window object on which the interface object of the
invoked constructor is found.
textarea elementautofocuscolsdisabledformmaxlengthnameplaceholderreadonlyrequiredrowswrapinterface 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 unsigned long textLength;
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 that bubbles named 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
IDL 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 IDL attribute.
The reset
algorithm for textarea elements is to set the
element's value to
the value of the element's textContent IDL
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 preceded 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 has
no more than character
width characters. For 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 IDL 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.
typeReturns the string "textarea".
valueReturns 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 non-negative numbers greater than zero. The maxLength IDL
attribute must reflect the maxlength content attribute,
limited to only non-negative numbers. The readOnly IDL
attribute must reflect the readonly content
attribute.
The type IDL
attribute must return the value "textarea".
The defaultValue
IDL attribute must act like the element's textContent
IDL 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 textLength IDL
attribute must return the code-point length of the
element's 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 labels. The select(), selectionStart,
selectionEnd,
and setSelectionRange()
methods and attributes expose the element's text selection.
Here is an example of a textarea being used for
unrestricted free-form text input in a form:
<p>If you have any comments, please let us know: <textarea cols=80 name=comments></textarea></p>
keygen elementautofocuschallengedisabledformkeytypenameinterface 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. User agents are
not required to support these values, and must only recognize values
whose corresponding algorithms they support.
| Keyword | State |
|---|---|
rsa
| RSA |
The invalid value default state is the unknown state. The missing value default state is the RSA state, if it is supported, or the unknown state otherwise.
This specification does not specify what key types user agents are to support — it is possible for a user agent to not support any key types at all.
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, using the md5WithRSAEncryption RSA signature algorithm
(the signature algorithm with MD5 and the RSA encryption
algorithm) referenced in section 2.2.1 ("RSA Signature
Algorithm") of RFC 3279, and defined in RFC 2313. [RFC3279] [RFC2313]
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
RFC 5280, with the algorithm field giving the
ASN.1 OID used to identify signature
algorithm, using the OIDs defined in section 2.2 ("Signature
Algorithms") of RFC 3279, and the parameters
field set up as required by RFC 3279 for AlgorithmIdentifier structures for that
algorithm. [X690] [RFC5280] [RFC3279]
Let spki be an ASN.1 SubjectPublicKeyInfo structure as defined by
RFC 5280, 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] [RFC5280]
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 RFC 5280. [RFC5280]
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.
typeReturns the string "keygen".
The challenge IDL
attribute must reflect the content attributes of the
same name.
The keytype
IDL attribute must reflect the content attributes of
the same name, limited to only known values.
The type IDL
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 labels.
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.
To generate a key pair, add the private key to the user's key store, and submit the public key to the server, markup such as the following can be used:
<form action="processkey.cgi" method="post" enctype="multipart/form-data"> <p><keygen name="key"></p> <p><input type=submit value="Submit key..."></p> </form>
The server will then receive a form submission with a packaged
RSA public key as the value of "key". This
can then be used for various purposes, such as generating a client
certificate, as mentioned above.
output elementforformnameinterface HTMLOutputElement : HTMLElement {
[PutForwards=value] readonly attribute DOMSettableTokenList 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);
readonly attribute NodeList labels;
};
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 IDL
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 IDL
attribute.
The reset
algorithm for output elements is to set the
element's textContent IDL attribute to the value of the
element's defaultValue
IDL 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.
typeReturns the string "output".
The value IDL
attribute must act like the element's textContent IDL
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 IDL
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 IDL attribute as well.
The type
attribute must return the string "output".
The htmlFor
IDL 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. The
labels attribute provides a list
of the element's labels.
Constraint validation: output
elements are always barred from constraint
validation.
A simple calculator could use output for its
display of calculated results:
<form onsubmit="return false"> <input name=a type=number step=any> + <input name=b type=number step=any> = <output onforminput="value = a.value + b.value"></output> </form>
progress elementprogress element descendants.valuemaxforminterface HTMLProgressElement : HTMLElement {
attribute float value;
attribute float max;
readonly attribute float position;
readonly attribute HTMLFormElement form;
readonly attribute NodeList labels;
};
The progress element represents the
completion progress of a task. The progress is either indeterminate,
indicating that progress is being made but that it is not clear how
much more work remains to be done before the task is complete
(e.g. because the task is waiting for a remote host to respond), or
the progress is a number in the range zero to a maximum, giving the
fraction of work that has so far been completed.
There are two attributes that determine the current task completion represented by the element.
The value
attribute specifies how much of the task has been completed, and the
max attribute
specifies how much work the task requires in total. The units are
arbitrary and not specified.
Authors are encouraged to also include the current value and the maximum value inline as text inside the element, so that the progress is made available to users of legacy user agents.
Here is a snippet of a Web application that shows the progress of some automated task:
<section>
<h2>Task Progress</h2>
<p>Progress: <progress id="p" max=100><span>0</span>%</progress></p>
<script>
var progressBar = document.getElementById('p');
function updateProgress(newValue) {
progressBar.value = newValue;
progressBar.getElementsByTagName('span')[0].textContent = newValue;
}
</script>
</section>
(The updateProgress() method in this example would
be called by some other code on the page to update the actual
progress bar as the task progressed.)
The value and max attributes, when present, must
have values that are valid
floating point numbers. The value attribute, if present, must
have a value equal to or greater than zero, and less than or equal
to the value of the max
attribute, if present, or 1.0, otherwise. The max attribute, if present, must
have a value greater than zero.
The progress element is the wrong
element to use for something that is just a gauge, as opposed to
task progress. For instance, indicating disk space usage using
progress would be inappropriate. Instead, the
meter element is available for such use cases.
User agent requirements: If the value attribute is omitted, then
the progress bar is an indeterminate progress bar. Otherwise, it is
a determinate progress bar.
If the progress bar is a determinate progress bar and the element
has a max attribute, the user
agent must parse the max
attribute's value according to the rules for parsing floating
point number values. If this does not result in an error, and
if the parsed value is greater than zero, then the maximum value of
the progress bar is that value. Otherwise, if the element has no
max attribute, or if it has
one but parsing it resulted in an error, or if the parsed value was
less than or equal to zero, then the maximum value of the progress
bar is 1.0.
If the progress bar is a determinate progress bar, user agents
must parse the value
attribute's value according to the rules for parsing floating
point number values. If this does not result in an error, and
if the parsed value is less than the maximum value and greater than
zero, then the current value of the progress bar is that parsed
value. Otherwise, if the parsed value was greater than or equal to
the maximum value, then the current value of the progress bar is the
maximum value of the progress bar. Otherwise, if parsing the value attribute's value resulted
in an error, or a number less than or equal to zero, then the
current value of the progress bar is zero.
UA requirements for showing the progress bar:
When representing a progress element to the user, the
UA should indicate whether it is a determinate or indeterminate
progress bar, and in the former case, should indicate the relative
position of the current value relative to the maximum value.
The max and value IDL attributes
must reflect the respective content attributes of the
same name. When the relevant content attributes are absent, the IDL
attributes must return zero.
The form attribute is used to
explicitly associate the progress element with its
form owner.
Constraint validation: progress
elements are always barred from constraint
validation.
positionFor a determinate progress bar (one with known current and maximum values), returns the result of dividing the current value by the maximum value.
For an indeterminate progress bar, returns −1.
If the progress bar is an indeterminate progress bar, then the
position IDL
attribute must return −1. Otherwise, it must return the result of
dividing the current value by the maximum value.
The labels attribute provides
a list of the element's labels.
meter elementmeter element descendants.valueminmaxlowhighoptimumforminterface HTMLMeterElement : HTMLElement {
attribute float value;
attribute float min;
attribute float max;
attribute float low;
attribute float high;
attribute float optimum;
readonly attribute HTMLFormElement form;
readonly attribute NodeList labels;
};
The meter element represents a scalar
measurement within a known range, or a fractional value; for example
disk usage, the relevance of a query result, or the fraction of a
voting population to have selected a particular candidate.
This is also known as a gauge.
The meter element should not be used to
indicate progress (as in a progress bar). For that role, HTML
provides a separate progress element.
The meter element also does not
represent a scalar value of arbitrary range — for example, it
would be wrong to use this to report a weight, or height, unless
there is a known maximum value.
There are six attributes that determine the semantics of the gauge represented by the element.
The min attribute
specifies the lower bound of the range, and the max attribute specifies
the upper bound. The value attribute
specifies the value to have the gauge indicate as the "measured"
value.
The other three attributes can be used to segment the gauge's
range into "low", "medium", and "high" parts, and to indicate which
part of the gauge is the "optimum" part. The low attribute specifies
the range that is considered to be the "low" part, and the high attribute specifies
the range that is considered to be the "high" part. The optimum attribute
gives the position that is "optimum"; if that is higher than the
"high" value then this indicates that the higher the value, the
better; if it's lower than the "low" mark then it indicates that
lower values are better, and naturally if it is in between then it
indicates that neither high nor low values are good.
Authoring
requirements: The value attribute must be
specified. The value, min, low, high, max, and optimum attributes, when present,
must have values that are valid floating point numbers.
In addition, the attributes' values are further constrained:
Let value be the value attribute's number.
If the min attribute
attribute is specified, then let minimum be that
attribute's value; otherwise, let it be zero.
If the max attribute
attribute is specified, then let maximum be that
attribute's value; otherwise, let it be 1.0.
The following inequalities must hold, as applicable:
low ≤ maximum (if low is specified)high ≤ maximum (if high is specified)optimum ≤ maximum (if optimum is specified)low ≤ high (if both low and high are specified)If no minimum or maximum is specified, then the range is assumed to be 0..1, and the value thus has to be within that range.
Authors are encouraged to include a textual representation of the
gauge's state in the element's contents, for users of user agents
that do not support the meter element.
The following examples show three gauges that would all be three-quarters full:
Storage space usage: <meter value=6 max=8>6 blocks used (out of 8 total)</meter> Voter turnout: <meter value=0.75><img alt="75%" src="graph75.png"></meter> Tickets sold: <meter min="0" max="100" value="75"></meter>
The following example is incorrect use of the element, because it doesn't give a range (and since the default maximum is 1, both of the gauges would end up looking maxed out):
<p>The grapefruit pie had a radius of <meter value=12>12cm</meter> and a height of <meter value=2>2cm</meter>.</p> <!-- BAD! -->
Instead, one would either not include the meter element, or use the meter element with a defined range to give the dimensions in context compared to other pies:
<p>The grapefruit pie had a radius of 12cm and a height of 2cm.</p> <dl> <dt>Radius: <dd> <meter min=0 max=20 value=12>12cm</meter> <dt>Height: <dd> <meter min=0 max=10 value=2>2cm</meter> </dl>
There is no explicit way to specify units in the
meter element, but the units may be specified in the
title attribute in free-form text.
The example above could be extended to mention the units:
<dl> <dt>Radius: <dd> <meter min=0 max=20 value=12 title="centimeters">12cm</meter> <dt>Height: <dd> <meter min=0 max=10 value=2 title="centimeters">2cm</meter> </dl>
User agent requirements: User agents must parse
the min, max, value, low, high, and optimum attributes using the
rules for parsing floating point number values.
User agents must then use all these numbers to obtain values for six points on the gauge, as follows. (The order in which these are evaluated is important, as some of the values refer to earlier ones.)
If the min attribute is
specified and a value could be parsed out of it, then the minimum
value is that value. Otherwise, the minimum value is zero.
If the max attribute is
specified and a value could be parsed out of it, the maximum value
is that value. Otherwise, the maximum value is 1.0.
If the maximum value would be less than the minimum value, then the maximum value is actually the same as the minimum value.
If the value attribute is
specified and a value could be parsed out of it, then that value
is the actual value. Otherwise, the actual value is zero.
If the actual value would be less than the minimum value, then the actual value is actually the same as the minimum value.
If, on the other hand, the actual value would be greater than the maximum value, then the actual value is the maximum value.
If the low attribute is
specified and a value could be parsed out of it, then the low
boundary is that value. Otherwise, the low boundary is the same as
the minimum value.
If the low boundary is then less than the minimum value, then the low boundary is actually the same as the minimum value. Similarly, if the low boundary is greater than the maximum value, then it is actually the maximum value instead.
If the high attribute is
specified and a value could be parsed out of it, then the high
boundary is that value. Otherwise, the high boundary is the same
as the maximum value.
If the high boundary is then less than the low boundary, then the high boundary is actually the same as the low boundary. Similarly, if the high boundary is greater than the maximum value, then it is actually the maximum value instead.
If the optimum
attribute is specified and a value could be parsed out of it, then
the optimum point is that value. Otherwise, the optimum point is
the midpoint between the minimum value and the maximum value.
If the optimum point is then less than the minimum value, then the optimum point is actually the same as the minimum value. Similarly, if the optimum point is greater than the maximum value, then it is actually the maximum value instead.
All of which will result in the following inequalities all being true:
UA requirements for regions of the gauge: If the optimum point is equal to the low boundary or the high boundary, or anywhere in between them, then the region between the low and high boundaries of the gauge must be treated as the optimum region, and the low and high parts, if any, must be treated as suboptimal. Otherwise, if the optimum point is less than the low boundary, then the region between the minimum value and the low boundary must be treated as the optimum region, the region between the low boundary and the high boundary must be treated as a suboptimal region, and the region between the high boundary and the maximum value must be treated as an even less good region. Finally, if the optimum point is higher than the high boundary, then the situation is reversed; the region between the high boundary and the maximum value must be treated as the optimum region, the region between the high boundary and the low boundary must be treated as a suboptimal region, and the remaining region between the low boundary and the minimum value must be treated as an even less good region.
UA requirements for showing the gauge: When
representing a meter element to the user, the UA should
indicate the relative position of the actual value to the minimum
and maximum values, and the relationship between the actual value
and the three regions of the gauge.
The following markup:
<h3>Suggested groups</h3>
<menu type="toolbar">
<a href="?cmd=hsg" onclick="hideSuggestedGroups()">Hide suggested groups</a>
</menu>
<ul>
<li>
<p><a href="/group/comp.infosystems.www.authoring.stylesheets/view">comp.infosystems.www.authoring.stylesheets</a> -
<a href="/group/comp.infosystems.www.authoring.stylesheets/subscribe">join</a></p>
<p>Group description: <strong>Layout/presentation on the WWW.</strong></p>
<p><meter value="0.5">Moderate activity,</meter> Usenet, 618 subscribers</p>
</li>
<li>
<p><a href="/group/netscape.public.mozilla.xpinstall/view">netscape.public.mozilla.xpinstall</a> -
<a href="/group/netscape.public.mozilla.xpinstall/subscribe">join</a></p>
<p>Group description: <strong>Mozilla XPInstall discussion.</strong></p>
<p><meter value="0.25">Low activity,</meter> Usenet, 22 subscribers</p>
</li>
<li>
<p><a href="/group/mozilla.dev.general/view">mozilla.dev.general</a> -
<a href="/group/mozilla.dev.general/subscribe">join</a></p>
<p><meter value="0.25">Low activity,</meter> Usenet, 66 subscribers</p>
</li>
</ul>
Might be rendered as follows:

User agents may combine the value of
the title attribute and the other
attributes to provide context-sensitive help or inline text
detailing the actual values.
For example, the following snippet:
<meter min=0 max=60 value=23.2 title=seconds></meter>
...might cause the user agent to display a gauge with a tooltip saying "Value: 23.2 out of 60." on one line and "seconds" on a second line.
The form attribute is used to
explicitly associate the meter element with its
form owner.
Constraint validation: meter
elements are always barred from constraint
validation.
The min, max, value, low, high, and optimum IDL attributes
must reflect the respective content attributes of the
same name. When the relevant content attributes are absent, the IDL
attributes must return zero.
The labels attribute provides
a list of the element's labels.
The following example shows how a gauge could fall back to localized or pretty-printed text.
<p>Disk usage: <meter min=0 value=170261928 max=233257824>170 261 928 bytes used out of 233 257 824 bytes available</meter></p>
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 its nearest form element ancestor 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 case-sensitively 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.
formReturns the element's form owner.
Returns null if there isn't one.
Form-associated
elements have a form IDL 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 IDL
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 and is not a descendant of that
fieldset element's first legend element
child, if any.
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 IDL
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
IDL 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 true, 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 buttons (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
buttons 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.
This attribute is useful to include "save" buttons on forms that have validation constraints, to allow users to save their progress even though they haven't fully entered the data in the form. The following example shows a simple form that has two required fields. There are three buttons: one to submit the form, which requires both fields to be filled in; one to save the form so that the user can come back and fill it in later; and one to cancel the form altogether.
<form action="editor.cgi" method="post"> <p><label>Name: <input required name=fn></label></p> <p><label>Essay: <textarea name=essay></textarea></label></p> <p><input type=submit name=submit value="Submit essay"></p> <p><input type=submit formnovalidate name=save value="Save essay"></p> <p><input type=submit formnovalidate name=cancel value="Cancel"></p> </form>
The action, method, enctype, and target IDL attributes must
reflect the respective content attributes of the same
name. The noValidate IDL
attribute must reflect the novalidate content attribute. The
formAction IDL
attribute must reflect the formaction content attribute. The
formEnctype IDL
attribute must reflect the formenctype content attribute.
The formMethod IDL
attribute must reflect the formmethod content attribute. The
formNoValidate
IDL attribute must reflect the formnovalidate content
attribute. The formTarget IDL
attribute must reflect the formtarget content attribute.
A listed form-associated
element is a candidate for constraint validation
except when 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.