This section is non-normative.
A form is a component of a Web page that has form controls, such as text fields, buttons, checkboxes, range controls, or color pickers. A user can interact with such a form, providing data that can then be sent to the server for further processing (e.g. returning the results of a search or calculation). No client-side scripting is needed in many cases, though an API is available so that scripts can augment the user experience or use forms for purposes other than submitting data to a server.
Writing a form consists of several steps, which can be performed in any order: writing the user interface, implementing the server-side processing, and configuring the user interface to communicate with the server.
This section is non-normative.
For the purposes of this brief introduction, we will create a pizza ordering form.
Any form starts with a form
element, inside which
are placed the controls. Most controls are represented by the
input
element, which by default provides a one-line
text field. To label a control, the label
element is
used; the label text and the control itself go inside the
label
element. Each part of a form is considered a
paragraph, and is typically separated from other parts
using p
elements. Putting this together, here is how
one might ask for the customer's name:
<form> <p><label>Customer name: <input></label></p> </form>
To let the user select the size of the pizza, we can use a set of
radio buttons. Radio buttons also use the input
element, this time with a type
attribute with the value radio
. To make the radio
buttons work as a group, they are given a common name using the
name
attribute. To group a batch
of controls together, such as, in this case, the radio buttons, one
can use the fieldset
element. The title of such a group
of controls is given by the first element in the
fieldset
, which has to be a legend
element.
<form> <p><label>Customer name: <input></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size> Small </label></p> <p><label> <input type=radio name=size> Medium </label></p> <p><label> <input type=radio name=size> Large </label></p> </fieldset> </form>
Changes from the previous step are highlighted.
To pick toppings, we can use checkboxes. These use the
input
element with a type
attribute with the value checkbox
:
<form> <p><label>Customer name: <input></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size> Small </label></p> <p><label> <input type=radio name=size> Medium </label></p> <p><label> <input type=radio name=size> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox> Bacon </label></p> <p><label> <input type=checkbox> Extra Cheese </label></p> <p><label> <input type=checkbox> Onion </label></p> <p><label> <input type=checkbox> Mushroom </label></p> </fieldset> </form>
The pizzeria for which this form is being written is always
making mistakes, so it needs a way to contact the customer. For this
purpose, we can use form controls specifically for telephone numbers
(input
elements with their type
attribute set to tel
) and e-mail addresses
(input
elements with their type
attribute set to email
):
<form> <p><label>Customer name: <input></label></p> <p><label>Telephone: <input type=tel></label></p> <p><label>E-mail address: <input type=email></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size> Small </label></p> <p><label> <input type=radio name=size> Medium </label></p> <p><label> <input type=radio name=size> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox> Bacon </label></p> <p><label> <input type=checkbox> Extra Cheese </label></p> <p><label> <input type=checkbox> Onion </label></p> <p><label> <input type=checkbox> Mushroom </label></p> </fieldset> </form>
We can use an input
element with its type
attribute set to time
to ask for a delivery
time. Many of these form controls have attributes to control exactly
what values can be specified; in this case, three attributes of
particular interest are min
,
max
, and step
. These set the minimum time, the
maximum time, and the interval between allowed values (in
seconds). This pizzeria only delivers between 11am and 9pm, and
doesn't promise anything better than 15 minute increments, which we
can mark up as follows:
<form> <p><label>Customer name: <input></label></p> <p><label>Telephone: <input type=tel></label></p> <p><label>E-mail address: <input type=email></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size> Small </label></p> <p><label> <input type=radio name=size> Medium </label></p> <p><label> <input type=radio name=size> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox> Bacon </label></p> <p><label> <input type=checkbox> Extra Cheese </label></p> <p><label> <input type=checkbox> Onion </label></p> <p><label> <input type=checkbox> Mushroom </label></p> </fieldset> <p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900"></label></p> </form>
The textarea
element can be used to provide a
free-form text field. In this instance, we are going to use it to
provide a space for the customer to give delivery instructions:
<form> <p><label>Customer name: <input></label></p> <p><label>Telephone: <input type=tel></label></p> <p><label>E-mail address: <input type=email></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size> Small </label></p> <p><label> <input type=radio name=size> Medium </label></p> <p><label> <input type=radio name=size> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox> Bacon </label></p> <p><label> <input type=checkbox> Extra Cheese </label></p> <p><label> <input type=checkbox> Onion </label></p> <p><label> <input type=checkbox> Mushroom </label></p> </fieldset> <p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900"></label></p> <p><label>Delivery instructions: <textarea></textarea></label></p> </form>
Finally, to make the form submittable we use the
button
element:
<form> <p><label>Customer name: <input></label></p> <p><label>Telephone: <input type=tel></label></p> <p><label>E-mail address: <input type=email></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size> Small </label></p> <p><label> <input type=radio name=size> Medium </label></p> <p><label> <input type=radio name=size> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox> Bacon </label></p> <p><label> <input type=checkbox> Extra Cheese </label></p> <p><label> <input type=checkbox> Onion </label></p> <p><label> <input type=checkbox> Mushroom </label></p> </fieldset> <p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900"></label></p> <p><label>Delivery instructions: <textarea></textarea></label></p> <p><button>Submit order</button></p> </form>
This section is non-normative.
The exact details for writing a server-side processor are out of
scope for this specification. For the purposes of this introduction,
we will assume that the script at https://pizza.example.com/order.cgi
is configured to
accept submissions using the application/x-www-form-urlencoded
format, expecting the following parameters sent in an HTTP POST
body:
custname
custtel
custemail
size
small
, medium
, or large
toppings
bacon
, cheese
, onion
, and mushroom
delivery
comments
This section is non-normative.
Form submissions are exposed to servers in a variety of ways,
most commonly as HTTP GET or POST requests. To specify the exact
method used, the method
attribute is specified on the form
element. This
doesn't specify how the form data is encoded, though; to specify
that, you use the enctype
attribute. You also have to specify the URL of the
service that will handle the submitted data, using the action
attribute.
For each form control you want submitted, you then have to give a
name that will be used to refer to the data in the submission. We
already specified the name for the group of radio buttons; the same
attribute (name
) also specifies
the submission name. Radio buttons can be distinguished from each
other in the submission by giving them different values, using the
value
attribute.
Multiple controls can have the same name; for example, here we
give all the checkboxes the same name, and the server distinguishes
which checkbox was checked by seeing which values are submitted with
that name — like the radio buttons, they are also given unique
values with the value
attribute.
Given the settings in the previous section, this all becomes:
<form method="post" enctype="application/x-www-form-urlencoded" action="https://pizza.example.com/order.cgi"> <p><label>Customer name: <input name="custname"></label></p> <p><label>Telephone: <input type=tel name="custtel"></label></p> <p><label>E-mail address: <input type=email name="custemail"></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size value="small"> Small </label></p> <p><label> <input type=radio name=size value="medium"> Medium </label></p> <p><label> <input type=radio name=size value="large"> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox name="topping" value="bacon"> Bacon </label></p> <p><label> <input type=checkbox name="topping" value="cheese"> Extra Cheese </label></p> <p><label> <input type=checkbox name="topping" value="onion"> Onion </label></p> <p><label> <input type=checkbox name="topping" value="mushroom"> Mushroom </label></p> </fieldset> <p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900" name="delivery"></label></p> <p><label>Delivery instructions: <textarea name="comments"></textarea></label></p> <p><button>Submit order</button></p> </form>
For example, if the customer entered "Denise Lawrence" as their name, "555-321-8642" as their telephone number, did not specify an e-mail address, asked for a medium-sized pizza, selected the Extra Cheese and Mushroom toppings, entered a delivery time of 7pm, and left the delivery instructions text field blank, the user agent would submit the following to the online Web service:
custname=Denise+Lawrence&custtel=555-321-8624&custemail=&size=medium&topping=cheese&topping=mushroom&delivery=19%3A00&comments=
This section is non-normative.
Forms can be annotated in such a way that the user agent will check the user's input before the form is submitted. The server still has to verify the input is valid (since hostile users can easily bypass the form validation), but it allows the user to avoid the wait incurred by having the server be the sole checker of the user's input.
The simplest annotation is the required
attribute, which can be
specified on input
elements to indicate that the form
is not to be submitted until a value is given. By adding this
attribute to the customer name and delivery time fields, we allow
the user agent to notify the user when the user submits the form
without filling in those fields:
<form method="post" enctype="application/x-www-form-urlencoded" action="https://pizza.example.com/order.cgi"> <p><label>Customer name: <input name="custname" required></label></p> <p><label>Telephone: <input type=tel name="custtel"></label></p> <p><label>E-mail address: <input type=email name="custemail"></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size value="small"> Small </label></p> <p><label> <input type=radio name=size value="medium"> Medium </label></p> <p><label> <input type=radio name=size value="large"> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox name="topping" value="bacon"> Bacon </label></p> <p><label> <input type=checkbox name="topping" value="cheese"> Extra Cheese </label></p> <p><label> <input type=checkbox name="topping" value="onion"> Onion </label></p> <p><label> <input type=checkbox name="topping" value="mushroom"> Mushroom </label></p> </fieldset> <p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900" name="delivery" required></label></p> <p><label>Delivery instructions: <textarea name="comments"></textarea></label></p> <p><button>Submit order</button></p> </form>
It is also possible to limit the length of the input, using the
maxlength
attribute. By
adding this to the textarea
element, we can limit users
to 1000 characters, preventing them from writing huge essays to the
busy delivery drivers instead of staying focused and to the
point:
<form method="post" enctype="application/x-www-form-urlencoded" action="https://pizza.example.com/order.cgi"> <p><label>Customer name: <input name="custname" required></label></p> <p><label>Telephone: <input type=tel name="custtel"></label></p> <p><label>E-mail address: <input type=email name="custemail"></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size value="small"> Small </label></p> <p><label> <input type=radio name=size value="medium"> Medium </label></p> <p><label> <input type=radio name=size value="large"> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox name="topping" value="bacon"> Bacon </label></p> <p><label> <input type=checkbox name="topping" value="cheese"> Extra Cheese </label></p> <p><label> <input type=checkbox name="topping" value="onion"> Onion </label></p> <p><label> <input type=checkbox name="topping" value="mushroom"> Mushroom </label></p> </fieldset> <p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900" name="delivery" required></label></p> <p><label>Delivery instructions: <textarea name="comments" maxlength=1000></textarea></label></p> <p><button>Submit order</button></p> </form>
This section is non-normative.
In this pizza delivery example, the times are specified in the format "HH:MM": two digits for the hour, in 24-hour format, and two digits for the time. (Seconds could also be specified, though they are not necessary in this example.)
In some locales, however, times are often expressed differently when presented to users. For example, in the United States, it is still common to use the 12-hour clock with an am/pm indicator, as in "2pm". In France, it is common to separate the hours from the minutes using an "h" character, as in "14h00".
Similar issues exist with dates, with the added complication that even the order of the components is not always consistent — for example, in Cyprus the first of February 2003 would typically be written "1/2/03", while that same date in Japan would typically be written as "2003年02月01日" — and even with numbers, where locales differ, for example, in what punctuation is used as the decimal separator and the thousands separator.
It therefore is important to distinguish the time, date, and number formats used in HTML and in form submissions, which are always the formats defined in this specification (and based on the well-established ISO 8601 standard for computer-readable date and time formats), from the time, date, and number formats presented to the user by the browser and accepted as input from the user by the browser.
The format used "on the wire", i.e. in HTML markup and in form submissions, is intended to be computer-readable and consistent irrespective of the user's locale. Dates, for instance, are always written in the format "YYYY-MM-DD", as in "2003-02-01". Users are not expected to ever see this format.
The time, date, or number given by the page in the wire format is then translated to the user's preferred presentation (based on user preferences or on the locale of the page itself), before being displayed to the user. Similarly, after the user inputs a time, date, or number using their preferred format, the user agent converts it back to the wire format before putting it in the DOM or submitting it.
This allows scripts in pages and on servers to process times, dates, and numbers in a consistent manner without needing to support dozens of different formats, while still supporting the users' needs.
See also the implementation notes regarding localization of form controls.
Mostly for historical reasons, elements in this section fall into several overlapping (but subtly different) categories in addition to the usual ones like flow content, phrasing content, and interactive content.
A number of the elements are form-associated elements, which means they can have a
form owner and, to expose this, have a form
content attribute with a matching
form
IDL attribute.
The form-associated elements fall into several subcategories:
Denotes elements that are listed in the form.elements
and fieldset.elements
APIs.
Denotes elements that can be used for constructing the form data
set when a form
element is submitted.
Some submittable elements can be, depending on their attributes, buttons. The prose below defines when an element is a button. Some buttons are specifically submit buttons.
Denotes elements that can be affected when a form
element is reset.
Some elements, not all of them form-associated, are categorized as labelable elements. These are elements
that can be associated with a label
element.
button
input
(if the type
attribute is not in the Hidden state)keygen
meter
output
progress
select
textarea
form
elementform
element descendants.accept-charset
action
autocomplete
enctype
method
name
novalidate
target
[OverrideBuiltins] interface HTMLFormElement : HTMLElement { attribute DOMString acceptCharset; attribute DOMString action; attribute DOMString autocomplete; attribute DOMString enctype; attribute DOMString encoding; attribute DOMString method; attribute DOMString name; attribute boolean noValidate; attribute DOMString target; readonly attribute HTMLFormControlsCollection elements; readonly attribute long length; getter Element (unsigned long index); getter object (DOMString name); void submit(); void reset(); boolean checkValidity(); };
The form
element represents a
collection of form-associated
elements, some of which can represent editable values that
can be submitted to a server for processing.
The accept-charset
attribute gives the character encodings that are to be used for the
submission. If specified, the value must be an ordered set of
unique space-separated tokens that are ASCII
case-insensitive, and each token must be an ASCII
case-insensitive match for the preferred MIME
name of an ASCII-compatible character encoding.
[IANACHARSET]
The name
attribute
represents the form
's name within the forms
collection. The value must
not be the empty string, and the value must be unique amongst the
form
elements in the forms
collection that it is in, if
any.
The autocomplete
attribute is an enumerated attribute. The attribute has
two states. The on
keyword maps to the on state, and the
off
keyword maps to
the off
state. The attribute may also be omitted. The missing value
default is the on state. The off state indicates
that by default, input
elements in the form will have
their resulting autocompletion state set to off; the on state indicates
that by default, input
elements in the form will have
their resulting autocompletion state set to on.
The action
, enctype
, method
, novalidate
, and target
attributes are attributes
for form submission.
elements
Returns an HTMLCollection
of the form controls in
the form (excluding image buttons for historical reasons).
length
Returns the number of form controls in the form (excluding image buttons for historical reasons).
Returns the indexth element in the form (excluding image buttons for historical reasons).
Returns the form control (or, if there are several, a
RadioNodeList
of the form controls) in the form with
the given ID or name
(excluding image buttons for
historical reasons); or, if there are none, returns the
img
element with the given ID.
Once an element has been referenced using a particular name,
that name will continue being available as a way to reference that
element in this method, even if the element's actual ID or name
changes, for as long as the
element remains in the Document
.
If there are multiple matching items, then a
RadioNodeList
object containing all those elements is
returned.
submit
()Submits the form.
reset
()Resets the form.
checkValidity
()Returns true if the form's controls are all valid; otherwise, returns false.
The autocomplete
IDL
attribute must reflect the content attribute of the
same name, limited to only known values.
The name
IDL
attribute must reflect the content attribute of the
same name.
The acceptCharset
IDL
attribute must reflect the accept-charset
content
attribute.
The elements
IDL attribute must return an HTMLFormControlsCollection
rooted at the Document
node while the form
element is in a Document
and rooted at the
form
element itself when it is not, whose filter
matches listed elements whose
form owner is the form
element, with the
exception of input
elements whose type
attribute is in the Image Button state, which must,
for historical reasons, be excluded from this particular
collection.
The length
IDL
attribute must return the number of nodes represented by the elements
collection.
The supported property indices at any instant are
the indices supported by the object returned by the elements
attribute at that
instant.
When a form
element is indexed for indexed property retrieval,
the user agent must return the value returned by the item
method on
the elements
collection, when
invoked with the given index as its argument.
Each form
element has a mapping of names to elements
called the past names map. It is used to persist names of
controls even when they change names.
The supported property names consist of the values
of all the id
and name
attributes of all the listed elements and img
elements that are descendants of the form
element, and
all the names currently in the past names map.
When a form
element is indexed for named property
retrieval, the user agent must run the following steps:
Let candidates be a live
RadioNodeList
object containing all the listed elements that are descendants
of the form
element and that have either an id
attribute or a name
attribute equal to name, in tree order.
If candidates is empty, let candidates be a live
RadioNodeList
object containing all the
img
elements that are descendants of the
form
element and that have either an id
attribute or a name
attribute equal to name, in tree order.
If candidates is empty, name is the name of one of the entries in the
form
element's past names map: return the
object associated with name in that
map.
If candidates contains more than one node, return candidates and abort these steps.
Otherwise, candidates contains exactly
one node. Add a mapping from name to the node
in candidates in the form
element's
past names map, replacing the previous entry with the
same name, if any.
Return the node in candidates.
If an element listed in the form
element's past
names map is removed from the Document
, then its
entries must be removed from the map.
The submit()
method, when invoked, must submit the form
element from the form
element itself, with the submitted from submit()
method flag set.
The reset()
method, when invoked, must run the following steps:
If the form
element is marked as locked for
reset, then abort these steps.
Mark the form
element as locked for
reset.
Unmark the form
element as locked for
reset.
If the checkValidity()
method is invoked, the user agent must statically validate the
constraints of the form
element, and return true
if the constraint validation return a positive result, and
false if it returned a negative result.
This example shows two search forms:
<form action="http://www.google.com/search" method="get"> <label>Google: <input type="search" name="q"></label> <input type="submit" value="Search..."> </form> <form action="http://www.bing.com/search" method="get"> <label>Bing: <input type="search" name="q"></label> <input type="submit" value="Search..."> </form>
fieldset
elementlegend
element, followed by flow content.disabled
form
name
interface HTMLFieldSetElement : HTMLElement { attribute boolean disabled; readonly attribute HTMLFormElement? form; attribute DOMString name; readonly attribute DOMString type; readonly attribute HTMLFormControlsCollection elements; readonly attribute boolean willValidate; readonly attribute ValidityState validity; readonly attribute DOMString validationMessage; boolean checkValidity(); void setCustomValidity(DOMString error); };
The fieldset
element represents a set
of form controls optionally grouped under a common name.
The name of the group is given by the first legend
element that is a child of the fieldset
element, if
any. The remainder of the descendants form the group.
The disabled
attribute, when specified, causes all the form control descendants
of the fieldset
element, excluding those that are
descendants of the fieldset
element's first
legend
element child, if any, to be disabled.
The form
attribute is used to
explicitly associate the fieldset
element with its
form owner. The name
attribute represents the element's name.
type
Returns the string "fieldset".
elements
Returns an HTMLFormControlsCollection
of the form
controls in the element.
The disabled
IDL
attribute must reflect the content attribute of the
same name.
The type
IDL
attribute must return the string "fieldset
".
The elements
IDL
attribute must return an HTMLFormControlsCollection
rooted at the fieldset
element, whose filter matches
listed elements.
The willValidate
, validity
, and validationMessage
attributes, and the checkValidity()
and setCustomValidity()
methods, are part of the constraint validation API. The
form
and name
IDL attributes are part of the
element's forms API.
This example shows a fieldset
element being used to
group a set of related controls:
<fieldset> <legend>Display</legend> <p><label><input type=radio name=c value=0 checked> Black on White</label> <p><label><input type=radio name=c value=1> White on Black</label> <p><label><input type=checkbox name=g> Use grayscale</label> <p><label>Enhance contrast <input type=range name=e list=contrast min=0 max=100 value=0 step=1></label> <datalist id=contrast> <option label=Normal value=0> <option label=Maximum value=100> </datalist> </fieldset>
The following snippet shows a fieldset with a checkbox in the legend that controls whether or not the fieldset is enabled. The contents of the fieldset consist of two required text fields and an optional year/month control.
<fieldset name="clubfields" disabled> <legend> <label> <input type=checkbox name=club onchange="form.clubfields.disabled = !checked"> Use Club Card </label> </legend> <p><label>Name on card: <input name=clubname required></label></p> <p><label>Card number: <input name=clubnum required pattern="[-0-9]+"></label></p> <p><label>Expiry date: <input name=clubexp type=month></label></p> </fieldset>
You can also nest fieldset
elements. Here is an
example expanding on the previous one that does so:
<fieldset name="clubfields" disabled> <legend> <label> <input type=checkbox name=club onchange="form.clubfields.disabled = !checked"> Use Club Card </label> </legend> <p><label>Name on card: <input name=clubname required></label></p> <fieldset name="numfields"> <legend> <label> <input type=radio checked name=clubtype onchange="form.numfields.disabled = !checked"> My card has numbers on it </label> </legend> <p><label>Card number: <input name=clubnum required pattern="[-0-9]+"></label></p> </fieldset> <fieldset name="letfields" disabled> <legend> <label> <input type=radio name=clubtype onchange="form.letfields.disabled = !checked"> My card has letters on it </label> </legend> <p><label>Card code: <input name=clublet required pattern="[A-Za-z]+"></label></p> </fieldset> </fieldset>
In this example, if the outer "Use Club Card" checkbox is not
checked, everything inside the outer fieldset
,
including the two radio buttons in the legends of the two nested
fieldset
s, will be disabled. However, if the checkbox
is checked, then the radio buttons will both be enabled and will
let you select which of the two inner fieldset
s is to
be enabled.
legend
elementfieldset
element.interface HTMLLegendElement : HTMLElement { readonly attribute HTMLFormElement? form; };
The legend
element represents a caption
for the rest of the contents of the legend
element's
parent fieldset
element, if
any.
form
Returns the element's form
element, if any, or
null otherwise.
The form
IDL
attribute's behavior depends on whether the legend
element is in a fieldset
element or not. If the
legend
has a fieldset
element as its
parent, then the form
IDL
attribute must return the same value as the form
IDL attribute on that
fieldset
element. Otherwise, it must return null.
label
elementlabel
elements.form
for
interface HTMLLabelElement : HTMLElement { readonly attribute HTMLFormElement? form; attribute DOMString htmlFor; readonly attribute HTMLElement? control; };
The label
represents a caption in a
user interface. The caption can be associated with a specific form
control, known as the label
element's labeled control, either using for
attribute, or by putting the form
control inside the label
element itself.
Except where otherwise specified by the following rules, a
label
element has no labeled control.
The for
attribute
may be specified to indicate a form control with which the caption
is to be associated. If the attribute is specified, the attribute's
value must be the ID of a labelable element in the same
Document
as the label
element. If the attribute is specified and there is an element
in the Document
whose ID is equal to the value of the for
attribute, and the first such
element is a labelable element,
then that element is the label
element's labeled
control.
If the for
attribute is not
specified, but the label
element has a labelable element descendant, then the
first such descendant in tree order is the
label
element's labeled control.
The label
element's exact default presentation and
behavior, in particular what its activation behavior
might be, if anything, should match the platform's label behavior.
The activation behavior of a label
element
for events targeted at interactive content descendants
of a label
element, and any descendants of those
interactive content descendants, must be to do
nothing.
For example, on platforms where clicking a checkbox label checks
the checkbox, clicking the label
in the following
snippet could trigger the user agent to run synthetic click
activation steps on the input
element, as if
the element itself had been triggered by the user:
<label><input type=checkbox name=lost> Lost</label>
On other platforms, the behavior might be just to focus the control, or do nothing.
The form
attribute is used to
explicitly associate the label
element with its
form owner.
The following example shows three form controls each with a label, two of which have small text showing the right format for users to use.
<p><label>Full name: <input name=fn> <small>Format: First Last</small></label></p> <p><label>Age: <input name=age type=number min=0></label></p> <p><label>Post code: <input name=pc> <small>Format: AB12 3CD</small></label></p>
control
Returns the form control that is associated with this element.
The htmlFor
IDL
attribute must reflect the for
content attribute.
The control
IDL
attribute must return the label
element's labeled
control, if any, or null if there isn't one.
The form
IDL attribute is part
of the element's forms API.
labels
Returns a NodeList
of all the label
elements that the form control is associated with.
Labelable elements have a
NodeList
object associated with them that represents
the list of label
elements, in tree order,
whose labeled control is the element in question. The
labels
IDL attribute
of labelable elements, on
getting, must return that NodeList
object.
input
elementtype
attribute is not in the Hidden state: Interactive content.type
attribute is not in the Hidden state: Listed, labelable, submittable, and resettable form-associated element.type
attribute is in the Hidden state: Listed, submittable, and resettable form-associated element.type
attribute is not in the Hidden state: Palpable content.accept
alt
autocomplete
autofocus
checked
dirname
disabled
form
formaction
formenctype
formmethod
formnovalidate
formtarget
height
list
max
maxlength
min
multiple
name
pattern
placeholder
readonly
required
size
src
step
type
value
width
interface HTMLInputElement : HTMLElement {
attribute DOMString accept;
attribute DOMString alt;
attribute DOMString autocomplete;
attribute boolean autofocus;
attribute boolean defaultChecked;
attribute boolean checked;
attribute DOMString dirName;
attribute boolean disabled;
readonly attribute HTMLFormElement? form;
readonly attribute FileList? files;
attribute DOMString formAction;
attribute DOMString formEnctype;
attribute DOMString formMethod;
attribute boolean formNoValidate;
attribute DOMString formTarget;
attribute unsigned long height;
attribute boolean indeterminate;
readonly attribute HTMLElement? list;
attribute DOMString max;
attribute long maxLength;
attribute DOMString min;
attribute boolean multiple;
attribute DOMString name;
attribute DOMString pattern;
attribute DOMString placeholder;
attribute boolean readOnly;
attribute boolean required;
attribute unsigned long size;
attribute DOMString src;
attribute DOMString step;
attribute DOMString type;
attribute DOMString defaultValue;
[TreatNullAs=EmptyString] attribute DOMString value;
attribute Date? valueAsDate;
attribute unrestricted double valueAsNumber;
attribute unsigned long width;
void stepUp(optional long n);
void stepDown(optional long n);
readonly attribute boolean willValidate;
readonly attribute ValidityState validity;
readonly attribute DOMString validationMessage;
boolean checkValidity();
void setCustomValidity(DOMString error);
readonly attribute NodeList labels;
void select();
attribute unsigned long selectionStart;
attribute unsigned long selectionEnd;
attribute DOMString selectionDirection;
void setSelectionRange(unsigned long start, unsigned long end, optional DOMString direction);
};
The input
element represents a typed data field,
usually with a form control to allow the user to edit the data.
The type
attribute controls the data type (and associated control) of the
element. It is an enumerated attribute. The following
table lists the keywords and states for the attribute — the
keywords in the left column map to the states in the cell in the
second column on the same row as the keyword.
Keyword | State | Data type | Control type |
---|---|---|---|
hidden
| Hidden | An arbitrary string | n/a |
text
| Text | Text with no line breaks | A text field |
search
| Search | Text with no line breaks | Search field |
tel
| Telephone | Text with no line breaks | A text field |
url
| URL | An absolute URL | A text field |
email
| An e-mail address or list of e-mail addresses | A text field | |
password
| Password | Text with no line breaks (sensitive information) | A text field that obscures data entry |
datetime
| Date and Time | A date and time (year, month, day, hour, minute, second, fraction of a second) with the time zone set to UTC | A date and time control |
date
| Date | A date (year, month, day) with no time zone | A date control |
month
| Month | A date consisting of a year and a month with no time zone | A month control |
week
| Week | A date consisting of a week-year number and a week number with no time zone | A week control |
time
| Time | A time (hour, minute, seconds, fractional seconds) with no time zone | A time control |
datetime-local
| Local Date and Time | A date and time (year, month, day, hour, minute, second, fraction of a second) with no time zone | A date and time control |
number
| Number | A numerical value | A text field or spinner control |
range
| Range | A numerical value, with the extra semantic that the exact value is not important | A slider control or similar |
color
| Color | An sRGB color with 8-bit red, green, and blue components | A color well |
checkbox
| Checkbox | A set of zero or more values from a predefined list | A checkbox |
radio
| Radio Button | An enumerated value | A radio button |
file
| File Upload | Zero or more files each with a MIME type and optionally a file name | A label and a button |
submit
| Submit Button | An enumerated value, with the extra semantic that it must be the last value selected and initiates form submission | A button |
image
| Image Button | A coordinate, relative to a particular image's size, with the extra semantic that it must be the last value selected and initiates form submission | Either a clickable image, or a button |
reset
| Reset Button | n/a | A button |
button
| Button | n/a | A button |
The missing value default is the Text state.
Which of the accept
, alt
, autocomplete
, checked
, dirname
, formaction
, formenctype
, formmethod
, formnovalidate
, formtarget
, height
, list
, max
, maxlength
, min
, multiple
, pattern
, placeholder
, readonly
, required
, size
, src
, step
, and width
content attributes, the checked
, files
, valueAsDate
, valueAsNumber
, and list
IDL attributes, the select()
method, the selectionStart
,
selectionEnd
,
and selectionDirection
,
IDL attributes, the
setSelectionRange()
methods, the stepUp()
and
stepDown()
methods, and the
input
and change
events apply to an
input
element depends on the state of its type
attribute. The following table
is non-normative and summarizes which of
those content attributes, IDL attributes, methods, and events apply
to each state:
Hidden | Text, Search | URL, Telephone | Password | Date and Time, Date, Month, Week, Time | Local Date and Time | Number | Range | Color | Checkbox, Radio Button | File Upload | Submit Button | Image Button | Reset Button, Button | ||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Content attributes | |||||||||||||||
accept
| · | · | · | · | · | · | · | · | · | · | · | Yes | · | · | · |
alt
| · | · | · | · | · | · | · | · | · | · | · | · | · | Yes | · |
autocomplete
| · | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | · | · | · |
checked
| · | · | · | · | · | · | · | · | · | · | Yes | · | · | · | · |
dirname
| · | Yes | · | · | · | · | · | · | · | · | · | · | · | · | · |
formaction
| · | · | · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
formenctype
| · | · | · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
formmethod
| · | · | · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
formnovalidate
| · | · | · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
formtarget
| · | · | · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
height
| · | · | · | · | · | · | · | · | · | · | · | · | · | Yes | · |
list
| · | Yes | Yes | Yes | · | Yes | Yes | Yes | Yes | Yes | · | · | · | · | · |
max
| · | · | · | · | · | Yes | Yes | Yes | Yes | · | · | · | · | · | · |
maxlength
| · | Yes | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · | · |
min
| · | · | · | · | · | Yes | Yes | Yes | Yes | · | · | · | · | · | · |
multiple
| · | · | · | Yes | · | · | · | · | · | · | · | Yes | · | · | · |
pattern
| · | Yes | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · | · |
placeholder
| · | Yes | Yes | Yes | Yes | · | · | Yes | · | · | · | · | · | · | · |
readonly
| · | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | · | · | · | · | · |
required
| · | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | Yes | Yes | · | · | · |
size
| · | Yes | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · | · |
src
| · | · | · | · | · | · | · | · | · | · | · | · | · | Yes | · |
step
| · | · | · | · | · | Yes | Yes | Yes | Yes | · | · | · | · | · | · |
width
| · | · | · | · | · | · | · | · | · | · | · | · | · | Yes | · |
IDL attributes and methods | |||||||||||||||
checked
| · | · | · | · | · | · | · | · | · | · | Yes | · | · | · | · |
files
| · | · | · | · | · | · | · | · | · | · | · | Yes | · | · | · |
value
| default | value | value | value | value | value | value | value | value | value | default/on | filename | default | default | default |
valueAsDate
| · | · | · | · | · | Yes | · | · | · | · | · | · | · | · | · |
valueAsNumber
| · | · | · | · | · | Yes | Yes | Yes | Yes | · | · | · | · | · | · |
list
| · | Yes | Yes | Yes | · | Yes | Yes | Yes | Yes | Yes | · | · | · | · | · |
select()
| · | Yes | Yes | · | Yes | · | · | · | · | · | · | · | · | · | · |
selectionStart
| · | Yes | Yes | · | Yes | · | · | · | · | · | · | · | · | · | · |
selectionEnd
| · | Yes | Yes | · | Yes | · | · | · | · | · | · | · | · | · | · |
selectionDirection
| · | Yes | Yes | · | Yes | · | · | · | · | · | · | · | · | · | · |
setSelectionRange()
| · | Yes | Yes | · | Yes | · | · | · | · | · | · | · | · | · | · |
stepDown()
| · | · | · | · | · | Yes | Yes | Yes | Yes | · | · | · | · | · | · |
stepUp()
| · | · | · | · | · | Yes | Yes | Yes | Yes | · | · | · | · | · | · |
Events | |||||||||||||||
input event
| · | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | · | · | · |
change event
| · | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | · |
Some states of the type
attribute define a value sanitization algorithm.
Each input
element has a value, which is exposed by the value
IDL attribute. Some states
define an algorithm
to convert a string to a number, an algorithm to convert a
number to a string, an algorithm to convert a
string to a Date
object, and an algorithm to convert a
Date
object to a string, which are used by
max
,
min
,
step
,
valueAsDate
,
valueAsNumber
,
stepDown()
, and
stepUp()
.
Each input
element has a boolean dirty value flag. The
dirty value flag
must be initially set to false when the element is created, and must
be set to true whenever the user interacts with the control in a way
that changes the value. (It is
also set to true when the value is programmatically changed, as
described in the definition of the value
IDL attribute.)
The value
content attribute gives the default value of the input
element. When the value
content attribute is added,
set, or removed, if the control's dirty value flag is
false, the user agent must set the value of the element to the value of
the value
content attribute,
if there is one, or the empty string otherwise, and then run the
current value sanitization algorithm, if one is
defined.
Each input
element has a checkedness, which is exposed by
the checked
IDL
attribute.
Each input
element has a boolean dirty checkedness
flag. When it is true, the element is said to have a dirty
checkedness. The dirty checkedness
flag must be initially set to false when the element is
created, and must be set to true whenever the user interacts with
the control in a way that changes the checkedness.
The checked
content attribute is a boolean attribute that gives the
default checkedness of the
input
element. When the checked
content attribute is
added, if the control does not have dirty checkedness, the user
agent must set the checkedness of the element to
true; when the checked
content attribute is removed, if the control does not have dirty checkedness, the user
agent must set the checkedness of the element to
false.
The reset
algorithm for input
elements is to set the dirty value flag and
dirty checkedness
flag back to false, set the value of the element to the value of
the value
content attribute,
if there is one, or the empty string otherwise, set the checkedness of the element to true
if the element has a checked
content attribute and false if it does not, empty the list of selected files, and
then invoke the value sanitization algorithm, if the
type
attribute's current state
defines one.
Each input
element is either mutable or immutable. Except where
otherwise specified, an input
element is always mutable. Similarly, except where
otherwise specified, the user agent should not allow the user to
modify the element's value or
checkedness.
When an input
element is disabled, it is immutable.
The readonly
attribute can also in
some cases (e.g. for the Date state, but not the Checkbox state) make an
input
element immutable.
The cloning steps for
input
elements must propagate the value, dirty value flag,
checkedness, and dirty checkedness
flag from the node being cloned to the copy.
When an input
element is first created, the
element's rendering and behavior must be set to the rendering and
behavior defined for the type
attribute's state, and the value sanitization
algorithm, if one is defined for the type
attribute's state, must be
invoked.
When an input
element's type
attribute changes state, the
user agent must run the following steps:
If the previous state of the element's type
attribute put the value
IDL attribute in the value mode, and the element's
value is not the empty
string, and the new state of the element's type
attribute puts the value
IDL attribute in either the default mode or the default/on mode, then set
the element's value
content
attribute to the element's value.
Otherwise, if the previous state of the element's type
attribute put the value
IDL attribute in any mode
other than the value mode, and
the new state of the element's type
attribute puts the value
IDL attribute in the value mode, then set the value of the element to the value
of the value
content
attribute, if there is one, or the empty string otherwise, and
then set the control's dirty value flag to
false.
Update the element's rendering and behavior to the new state's.
Invoke the value sanitization algorithm, if one
is defined for the type
attribute's new state.
The form
attribute is used to
explicitly associate the input
element with its
form owner. The name
attribute represents the element's name. The disabled
attribute is used to make
the control non-interactive and to prevent its value from being
submitted. The autofocus
attribute controls focus.
The indeterminate
IDL
attribute must initially be set to false. On getting, it must return
the last value it was set to. On setting, it must be set to the new
value. It has no effect except for changing the appearance of checkbox controls.
The accept
, alt
, max
, min
, multiple
, pattern
, placeholder
, required
, size
, src
, and step
IDL attributes must
reflect the respective content attributes of the same
name. The dirName
IDL attribute
must reflect the dirname
content attribute. The readOnly
IDL attribute
must reflect the readonly
content attribute. The
defaultChecked
IDL attribute must reflect the checked
content attribute. The
defaultValue
IDL attribute must reflect the value
content attribute.
The autocomplete
and
type
IDL attributes
must reflect the respective content attributes of the
same name, limited to only known values. The maxLength
IDL
attribute must reflect the maxlength
content attribute,
limited to only non-negative numbers.
The IDL attributes width
and height
must return the
rendered width and height of the image, in CSS pixels, if an image
is being rendered, and is being rendered to a visual
medium; or else the intrinsic width and height of the image, in CSS
pixels, if an image is available
but not being rendered to a visual medium; or else 0, if no image is
available. When the
input
element's type
attribute is not in the Image Button state, then no
image is available. [CSS]
On setting, they must act as if they reflected the respective content attributes of the same name.
The willValidate
, validity
, and validationMessage
IDL
attributes, and the checkValidity()
and setCustomValidity()
methods, are part of the constraint validation API. The
labels
IDL attribute provides a
list of the element's label
s. The select()
, selectionStart
,
selectionEnd
,
selectionDirection
,
setRangeText()
,
and setSelectionRange()
methods and IDL attributes expose the element's text selection. The
autofocus
, disabled
, form
, and name
IDL attributes are part of the
element's forms API.
type
attributetype=hidden
)The input
element represents a value
that is not intended to be examined or manipulated by the user.
Constraint validation: If an input
element's type
attribute is in
the Hidden state, it is
barred from constraint validation.
If the name
attribute is
present and has a value that is a case-sensitive match
for the string "_charset_
", then the element's
value
attribute must be
omitted.
The
value
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
,
dirname
,
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
,
selectionStart
,
selectionEnd
,
selectionDirection
,
valueAsDate
, and
valueAsNumber
IDL attributes;
select()
,
setRangeText()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
type=text
) state and Search state (type=search
)When an input
element's type
attribute is in the Text state or the Search state, the rules in
this section apply.
The input
element represents a one line
plain text edit control for the element's value.
The difference between the Text state and the Search state is primarily stylistic: on platforms where search fields are distinguished from regular text fields, the Search state might result in an appearance consistent with the platform's search fields rather than appearing like a regular text field.
If the element is mutable, its value should be editable by the user. User agents must not allow users to insert "LF" (U+000A) or "CR" (U+000D) characters into the element's value.
If the element is mutable, the user agent should allow the user to change the writing direction of the element, setting it either to a left-to-right writing direction or a right-to-left writing direction. If the user does so, the user agent must then run the following steps:
Set the element's dir
attribute to "ltr
" if the user
selected a left-to-right writing direction, and "rtl
" if the user selected a
right-to-left writing direction.
Queue a task to fire a simple
event that bubbles named input
at the input
element.
The value
attribute, if
specified, must have a value that contains no "LF" (U+000A)
or "CR" (U+000D) characters.
The value sanitization algorithm is as follows: Strip line breaks from the value.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
dirname
,
list
,
maxlength
,
pattern
,
placeholder
,
readonly
,
required
, and
size
content attributes;
list
,
selectionStart
,
selectionEnd
,
selectionDirection
, and
value
IDL attributes;
select()
,
setRangeText()
, and
setSelectionRange()
methods.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
max
,
min
,
multiple
,
src
,
step
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
files
,
valueAsDate
, and
valueAsNumber
IDL attributes;
stepDown()
and
stepUp()
methods.
type=tel
)The input
element represents a control
for editing a telephone number given in the element's value.
If the element is mutable, its value should be editable by the user. User agents may change the spacing and, with care, the punctuation of values that the user enters. User agents must not allow users to insert "LF" (U+000A) or "CR" (U+000D) characters into the element's value.
The value
attribute, if
specified, must have a value that contains no "LF" (U+000A)
or "CR" (U+000D) characters.
The value sanitization algorithm is as follows: Strip line breaks from the value.
Unlike the URL and E-mail types, the Telephone type does not enforce a
particular syntax. This is intentional; in practice, telephone
number fields tend to be free-form fields, because there are a wide
variety of valid phone numbers. Systems that need to enforce a
particular format are encouraged to use the pattern
attribute or the setCustomValidity()
method
to hook into the client-side validation mechanism.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
list
,
maxlength
,
pattern
,
placeholder
,
readonly
,
required
, and
size
content attributes;
list
,
selectionStart
,
selectionEnd
,
selectionDirection
, and
value
IDL attributes;
select()
,
setRangeText()
, and
setSelectionRange()
methods.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
max
,
min
,
multiple
,
src
,
step
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
files
,
valueAsDate
, and
valueAsNumber
IDL attributes;
stepDown()
and
stepUp()
methods.
type=url
)The input
element represents a control
for editing a single absolute URL given in the
element's value.
If the element is mutable, the user agent should allow the user to change the URL represented by its value. User agents may allow the user to set the value to a string that is not a valid absolute URL, but may also or instead automatically escape characters entered by the user so that the value is always a valid absolute URL (even if that isn't the actual value seen and edited by the user in the interface). User agents should allow the user to set the value to the empty string. User agents must not allow users to insert "LF" (U+000A) or "CR" (U+000D) characters into the value.
The value
attribute, if
specified and not empty, must have a value that is a valid URL
potentially surrounded by spaces that is also an
absolute URL.
The value sanitization algorithm is as follows: Strip line breaks from the value, then strip leading and trailing whitespace from the value.
Constraint validation: While the value of the element is neither the empty string nor a valid absolute URL, the element is suffering from a type mismatch.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
list
,
maxlength
,
pattern
,
placeholder
,
readonly
,
required
, and
size
content attributes;
list
,
selectionStart
,
selectionEnd
,
selectionDirection
, and
value
IDL attributes;
select()
,
setRangeText()
, and
setSelectionRange()
methods.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
max
,
min
,
multiple
,
src
,
step
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
files
,
valueAsDate
, and
valueAsNumber
IDL attributes;
stepDown()
and
stepUp()
methods.
If a document contained the following markup:
<input type="url" name="location" list="urls"> <datalist id="urls"> <option label="MIME: Format of Internet Message Bodies" value="http://tools.ietf.org/html/rfc2045"> <option label="HTML 4.01 Specification" value="http://www.w3.org/TR/html4/"> <option label="Form Controls" value="http://www.w3.org/TR/xforms/slice8.html#ui-commonelems-hint"> <option label="Scalable Vector Graphics (SVG) 1.1 Specification" value="http://www.w3.org/TR/SVG/"> <option label="Feature Sets - SVG 1.1 - 20030114" value="http://www.w3.org/TR/SVG/feature.html"> <option label="The Single UNIX Specification, Version 3" value="http://www.unix-systems.org/version3/"> </datalist>
...and the user had typed "www.w3", and the user
agent had also found that the user had visited
http://www.w3.org/Consortium/#membership
and
http://www.w3.org/TR/XForms/
in the recent past, then
the rendering might look like this:
The first four URLs in this sample consist of the four URLs in the author-specified list that match the text the user has entered, sorted in some UA-defined manner (maybe by how frequently the user refers to those URLs). Note how the UA is using the knowledge that the values are URLs to allow the user to omit the scheme part and perform intelligent matching on the domain name.
The last two URLs (and probably many more, given the scrollbar's indications of more values being available) are the matches from the user agent's session history data. This data is not made available to the page DOM. In this particular case, the UA has no titles to provide for those values.
type=email
)How the E-mail state
operates depends on whether the multiple
attribute is specified
or not.
multiple
attribute is not specified on the elementThe input
element represents a
control for editing an e-mail address given in the element's value.
If the element is mutable, the user agent should allow the user to change the e-mail address represented by its value. User agents may allow the user to set the value to a string that is not a valid e-mail address. The user agent should act in a manner consistent with expecting the user to provide a single e-mail address. User agents should allow the user to set the value to the empty string. User agents must not allow users to insert "LF" (U+000A) or "CR" (U+000D) characters into the value. User agents may transform the value for display and editing; in particular, user agents should convert punycode in the value to IDN in the display and vice versa.
The value
attribute, if
specified and not empty, must have a value that is a single
valid e-mail address.
The value sanitization algorithm is as follows: Strip line breaks from the value, then strip leading and trailing whitespace from the value.
When the multiple
attribute is removed, the user agent must run the value
sanitization algorithm.
Constraint validation: While the value of the element is neither the empty string nor a single valid e-mail address, the element is suffering from a type mismatch.
multiple
attribute is specified on the elementThe element's values are the result of splitting on commas the element's value.
The input
element represents a
control for adding, removing, and editing the e-mail addresses
given in the element's values.
If the element is mutable, the user agent should allow the user to add, remove, and edit the e-mail addresses represented by its values. User agents may allow the user to set any individual value in the list of values to a string that is not a valid e-mail address, but must not allow users to set any individual value to a string containing "," (U+002C), "LF" (U+000A), or "CR" (U+000D) characters. User agents should allow the user to remove all the addresses in the element's values. User agents may transform the values for display and editing; in particular, user agents should convert punycode in the value to IDN in the display and vice versa.
Whenever the user changes the element's values, the user agent must run the following steps:
Let latest values be a copy of the element's values.
Strip leading and trailing whitespace from each value in latest values.
Let the element's value be the result of concatenating all the values in latest values, separating each value from the next by a single "," (U+002C) character, maintaining the list's order.
The value
attribute, if
specified, must have a value that is a valid e-mail address
list.
The value sanitization algorithm is as follows:
Split on commas the element's value, strip leading and trailing whitespace from each resulting token, if any, and let the element's values be the (possibly empty) resulting list of (possibly empty) tokens, maintaining the original order.
Let the element's value be the result of concatenating the element's values, separating each value from the next by a single "," (U+002C) character, maintaining the list's order.
When the multiple
attribute is set, the user agent must run the value
sanitization algorithm.
Constraint validation: While the value of the element is not a valid e-mail address list, the element is suffering from a type mismatch.
A valid e-mail address is a string that matches the
ABNF production 1*( atext / "." ) "@" ldh-str *( "." ldh-str )
where atext
is defined in RFC 5322
section 3.2.3, and ldh-str
is defined in
RFC 1034
section 3.5. [ABNF] [RFC5322] [RFC1034]
This requirement is a willful violation of RFC 5322, which defines a syntax for e-mail addresses that is simultaneously too strict (before the "@" character), too vague (after the "@" character), and too lax (allowing comments, whitespace characters, and quoted strings in manners unfamiliar to most users) to be of practical use here.
The following JavaScript- and Perl-compatible regular expression is an implementation of the above definition.
/^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*$/
A valid e-mail address list is a set of comma-separated tokens, where each token is itself a valid e-mail address. To obtain the list of tokens from a valid e-mail address list, and implementation must split the string on commas.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
list
,
maxlength
,
multiple
,
pattern
,
placeholder
,
readonly
,
required
, and
size
content attributes;
list
and
value
IDL attributes.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
max
,
min
,
src
,
step
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
files
,
selectionStart
,
selectionEnd
,
selectionDirection
,
valueAsDate
, and
valueAsNumber
IDL attributes;
select()
,
setRangeText()
,
setSelectionRange()
,
stepDown()
and
stepUp()
methods.
type=password
)The input
element represents a one line
plain text edit control for the element's value. The user agent should obscure
the value so that people other than the user cannot see it.
If the element is mutable, its value should be editable by the user. User agents must not allow users to insert "LF" (U+000A) or "CR" (U+000D) characters into the value.
The value
attribute, if
specified, must have a value that contains no "LF" (U+000A)
or "CR" (U+000D) characters.
The value sanitization algorithm is as follows: Strip line breaks from the value.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
maxlength
,
pattern
,
placeholder
,
readonly
,
required
, and
size
content attributes;
selectionStart
,
selectionEnd
,
selectionDirection
, and
value
IDL attributes;
select()
,
setRangeText()
, and
setSelectionRange()
methods.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
list
,
max
,
min
,
multiple
,
src
,
step
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
files
,
list
,
valueAsDate
, and
valueAsNumber
IDL attributes;
stepDown()
and
stepUp()
methods.
type=datetime
)When an input
element's type
attribute is in the Date and Time state, the
rules in this section apply.
The input
element represents a control
for setting the element's value to a string representing a
specific global date and
time. User agents may display the date and
time in whatever time zone is appropriate for the user.
If the element is mutable, the user agent should allow the user to change the global date and time represented by its value, as obtained by parsing a global date and time from it. User agents must not allow the user to set the value to a non-empty string that is not a valid normalized forced-UTC global date and time string, though user agents may allow the user to set and view the time in another time zone and silently translate the time to and from the UTC time zone in the value. If the user agent provides a user interface for selecting a global date and time, then the value must be set to a valid normalized forced-UTC global date and time string representing the user's selection. User agents should allow the user to set the value to the empty string.
See the introduction section for a discussion of the difference between the input format and submission format for date, time, and number form controls, and the implementation notes regarding localization of form controls.
The value
attribute, if
specified and not empty, must have a value that is a valid
global date and time string.
The value sanitization algorithm is as follows: If the value of the element is a valid global date and time string, then adjust the time so that the value represents the same point in time but expressed in the UTC time zone as a valid normalized forced-UTC global date and time string, otherwise, set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid global date and
time string. The max
attribute, if specified, must have a value that is a valid
global date and time string.
The step
attribute is
expressed in seconds. The step scale factor is 1000
(which converts the seconds to milliseconds, as used in the other
algorithms). The default step is 60
seconds.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest global date and time for which the element would not suffer from a step mismatch.
The algorithm to convert a
string to a number, given a string input,
is as follows: If parsing a global date and time from input results in an error, then return an error;
otherwise, return the number of milliseconds elapsed from midnight
UTC on the morning of 1970-01-01 (the time represented by the value
"1970-01-01T00:00:00.0Z
") to the parsed global date and time, ignoring leap
seconds.
The algorithm to convert a
number to a string, given a number input,
is as follows: Return a valid normalized forced-UTC
global date and time string that represents the global date and time that is input milliseconds after midnight UTC on the morning
of 1970-01-01 (the time represented by the value "1970-01-01T00:00:00.0Z
").
The algorithm to convert a
string to a Date
object, given a string input, is as follows: If parsing a global date and time
from input results in an error, then return an
error; otherwise, return a new
Date
object representing the parsed global date and time, expressed in
UTC.
The algorithm to convert a
Date
object to a string, given a
Date
object input, is as
follows: Return a valid normalized forced-UTC global
date and time string that represents the global date and time that is
represented by input.
The Date and Time state (and other date- and time-related states described in subsequent sections) is not intended for the entry of values for which a precise date and time relative to the contemporary calendar cannot be established. For example, it would be inappropriate for the entry of times like "one millisecond after the big bang", "the early part of the Jurassic period", or "a winter around 250 BCE".
For the input of dates before the introduction of the Gregorian
calendar, authors are encouraged to not use the Date and Time state (and
the other date- and time-related states described in subsequent
sections), as user agents are not required to support converting
dates and times from earlier periods to the Gregorian calendar, and
asking users to do so manually puts an undue burden on users. (This
is complicated by the manner in which the Gregorian calendar was
phased in, which occurred at different times in different
countries, ranging from partway through the 16th century all the
way to early in the 20th.) Instead, authors are encouraged to
provide fine-grained input controls using the select
element and input
elements with the Number state.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
,
valueAsDate
, and
valueAsNumber
IDL attributes;
stepDown()
and
stepUp()
methods.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
files
,
selectionStart
,
selectionEnd
, and
selectionDirection
IDL attributes;
select()
,
setRangeText()
, and
setSelectionRange()
methods.
The following fragment shows part of a calendar application. A user can specify a date and time for a meeting (in his local time zone, probably, though the user agent can allow the user to change that), and since the submitted data includes the time-zone offset, the application can ensure that the meeting is shown at the correct time regardless of the time zones used by all the participants.
<fieldset> <legend>Add Meeting</legend> <p><label>Meeting name: <input type=text name="meeting.label"></label> <p><label>Meeting time: <input type=datetime name="meeting.start"></label> </fieldset>
Had the application used the datetime-local
type
instead, the calendar application would have also had to explicitly
determine which time zone the user intended.
type=date
)The input
element represents a control
for setting the element's value to a string representing a
specific date.
If the element is mutable, the user agent should allow the user to change the date represented by its value, as obtained by parsing a date from it. User agents must not allow the user to set the value to a non-empty string that is not a valid date string. If the user agent provides a user interface for selecting a date, then the value must be set to a valid date string representing the user's selection. User agents should allow the user to set the value to the empty string.
See the introduction section for a discussion of the difference between the input format and submission format for date, time, and number form controls, and the implementation notes regarding localization of form controls.
The value
attribute, if
specified and not empty, must have a value that is a valid
date string.
The value sanitization algorithm is as follows: If the value of the element is not a valid date string, then set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid date
string. The max
attribute, if specified, must have a value that is a valid
date string.
The step
attribute is
expressed in days. The step scale factor is
86,400,000 (which converts the days to milliseconds, as used in the
other algorithms). The default step is 1 day.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest date for which the element would not suffer from a step mismatch.
The algorithm to convert a
string to a number, given a string input,
is as follows: If parsing
a date from input results in an error,
then return an error; otherwise, return the number of milliseconds
elapsed from midnight UTC on the morning of 1970-01-01 (the time
represented by the value "1970-01-01T00:00:00.0Z
") to midnight UTC on the
morning of the parsed date,
ignoring leap seconds.
The algorithm to convert a
number to a string, given a number input,
is as follows: Return a valid date string that
represents the date that, in UTC,
is current input milliseconds after midnight UTC
on the morning of 1970-01-01 (the time represented by the value
"1970-01-01T00:00:00.0Z
").
The algorithm to convert a
string to a Date
object, given a string input, is as follows: If parsing a date from input
results in an error, then return an error; otherwise, return a new Date
object
representing midnight UTC on the morning of the parsed date.
The algorithm to convert a
Date
object to a string, given a
Date
object input, is as
follows: Return a valid date string that
represents the date current at the
time represented by input in the UTC
time zone.
See the note on historical dates in the Date and Time state section.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
,
valueAsDate
, and
valueAsNumber
IDL attributes;
stepDown()
and
stepUp()
methods.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
selectionStart
,
selectionEnd
, and
selectionDirection
IDL attributes;
select()
,
setRangeText()
, and
setSelectionRange()
methods.
type=month
)The input
element represents a control
for setting the element's value to a string representing a
specific month.
If the element is mutable, the user agent should allow the user to change the month represented by its value, as obtained by parsing a month from it. User agents must not allow the user to set the value to a non-empty string that is not a valid month string. If the user agent provides a user interface for selecting a month, then the value must be set to a valid month string representing the user's selection. User agents should allow the user to set the value to the empty string.
See the introduction section for a discussion of the difference between the input format and submission format for date, time, and number form controls, and the implementation notes regarding localization of form controls.
The value
attribute, if
specified and not empty, must have a value that is a valid
month string.
The value sanitization algorithm is as follows: If the value of the element is not a valid month string, then set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid month
string. The max
attribute, if specified, must have a value that is a valid
month string.
The step
attribute is
expressed in months. The step scale factor is 1
(there is no conversion needed as the algorithms use months).
The default step is
1 month.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest month for which the element would not suffer from a step mismatch.
The algorithm to convert a string to a number, given a string input, is as follows: If parsing a month from input results in an error, then return an error; otherwise, return the number of months between January 1970 and the parsed month.
The algorithm to convert a number to a string, given a number input, is as follows: Return a valid month string that represents the month that has input months between it and January 1970.
The algorithm to convert a
string to a Date
object, given a string input, is as follows: If parsing a month from input results in an error, then return an error;
otherwise, return a new
Date
object representing midnight UTC on the
morning of the first day of the parsed month.
The algorithm to convert a
Date
object to a string, given a
Date
object input, is as
follows: Return a valid month string that
represents the month current at
the time represented by input in the UTC
time zone.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
,
valueAsDate
, and
valueAsNumber
IDL attributes;
stepDown()
and
stepUp()
methods.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
files
,
selectionStart
,
selectionEnd
, and
selectionDirection
IDL attributes;
select()
,
setRangeText()
, and
setSelectionRange()
methods.
type=week
)The input
element represents a control
for setting the element's value to a string representing a
specific week.
If the element is mutable, the user agent should allow the user to change the week represented by its value, as obtained by parsing a week from it. User agents must not allow the user to set the value to a non-empty string that is not a valid week string. If the user agent provides a user interface for selecting a week, then the value must be set to a valid week string representing the user's selection. User agents should allow the user to set the value to the empty string.
See the introduction section for a discussion of the difference between the input format and submission format for date, time, and number form controls, and the implementation notes regarding localization of form controls.
The value
attribute, if
specified and not empty, must have a value that is a valid
week string.
The value sanitization algorithm is as follows: If the value of the element is not a valid week string, then set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid week
string. The max
attribute, if specified, must have a value that is a valid
week string.
The step
attribute is
expressed in weeks. The step scale factor is
604,800,000 (which converts the weeks to milliseconds, as used in
the other algorithms). The default step is 1
week. The default step base is
−259,200,000 (the start of week 1970-W01).
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest week for which the element would not suffer from a step mismatch.
The algorithm to convert a
string to a number, given a string input,
is as follows: If parsing
a week string from input results in an
error, then return an error; otherwise, return the number of
milliseconds elapsed from midnight UTC on the morning of 1970-01-01
(the time represented by the value "1970-01-01T00:00:00.0Z
") to midnight UTC on the
morning of the Monday of the parsed week, ignoring leap seconds.
The algorithm to convert a
number to a string, given a number input,
is as follows: Return a valid week string that
represents the week that, in UTC,
is current input milliseconds after midnight UTC
on the morning of 1970-01-01 (the time represented by the value
"1970-01-01T00:00:00.0Z
").
The algorithm to convert a
string to a Date
object, given a string input, is as follows: If parsing a week from input
results in an error, then return an error; otherwise, return a new Date
object
representing midnight UTC on the morning of the Monday of the parsed
week.
The algorithm to convert a
Date
object to a string, given a
Date
object input, is as
follows: Return a valid week string that
represents the week current at the
time represented by input in the UTC
time zone.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
,
valueAsDate
, and
valueAsNumber
IDL attributes;
stepDown()
and
stepUp()
methods.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
files
,
selectionStart
,
selectionEnd
, and
selectionDirection
IDL attributes;
select()
,
setRangeText()
, and
setSelectionRange()
methods.
type=time
)The input
element represents a control
for setting the element's value to a string representing a
specific time.
If the element is mutable, the user agent should allow the user to change the time represented by its value, as obtained by parsing a time from it. User agents must not allow the user to set the value to a non-empty string that is not a valid time string. If the user agent provides a user interface for selecting a time, then the value must be set to a valid time string representing the user's selection. User agents should allow the user to set the value to the empty string.
See the introduction section for a discussion of the difference between the input format and submission format for date, time, and number form controls, and the implementation notes regarding localization of form controls.
The value
attribute, if
specified and not empty, must have a value that is a valid
time string.
The value sanitization algorithm is as follows: If the value of the element is not a valid time string, then set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid time
string. The max
attribute, if specified, must have a value that is a valid
time string.
The step
attribute is
expressed in seconds. The step scale factor is 1000
(which converts the seconds to milliseconds, as used in the other
algorithms). The default step is 60
seconds.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest time for which the element would not suffer from a step mismatch.
The algorithm to convert a string to a number, given a string input, is as follows: If parsing a time from input results in an error, then return an error; otherwise, return the number of milliseconds elapsed from midnight to the parsed time on a day with no time changes.
The algorithm to convert a number to a string, given a number input, is as follows: Return a valid time string that represents the time that is input milliseconds after midnight on a day with no time changes.
The algorithm to convert a
string to a Date
object, given a string input, is as follows: If parsing a time from input
results in an error, then return an error; otherwise, return a new Date
object
representing the parsed time in
UTC on 1970-01-01.
The algorithm to convert a
Date
object to a string, given a
Date
object input, is as
follows: Return a valid time string that
represents the UTC time component
that is represented by input.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
,
valueAsDate
, and
valueAsNumber
IDL attributes;
stepDown()
and
stepUp()
methods.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
files
,
selectionStart
,
selectionEnd
, and
selectionDirection
IDL attributes;
select()
,
setRangeText()
, and
setSelectionRange()
methods.
type=datetime-local
)When an input
element's type
attribute is in the Local Date and Time
state, the rules in this section apply.
The input
element represents a control
for setting the element's value to a string representing a
local date and time,
with no time-zone offset information.
If the element is mutable, the user agent should allow the user to change the date and time represented by its value, as obtained by parsing a date and time from it. User agents must not allow the user to set the value to a non-empty string that is not a valid normalized local date and time string. If the user agent provides a user interface for selecting a local date and time, then the value must be set to a valid normalized local date and time string representing the user's selection. User agents should allow the user to set the value to the empty string.
See the introduction section for a discussion of the difference between the input format and submission format for date, time, and number form controls, and the implementation notes regarding localization of form controls.
The value
attribute, if
specified and not empty, must have a value that is a valid
local date and time string.
The value sanitization algorithm is as follows: If the value of the element is a valid local date and time string, then set it to a valid normalized local date and time string representing the same date and time; otherwise, set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid local date and
time string. The max
attribute, if specified, must have a value that is a valid
local date and time string.
The step
attribute is
expressed in seconds. The step scale factor is 1000
(which converts the seconds to milliseconds, as used in the other
algorithms). The default step is 60
seconds.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest local date and time for which the element would not suffer from a step mismatch.
The algorithm to convert a
string to a number, given a string input,
is as follows: If parsing a date and time from input results in an error, then return an error;
otherwise, return the number of milliseconds elapsed from midnight
on the morning of 1970-01-01 (the time represented by the value
"1970-01-01T00:00:00.0
") to the parsed local date and time, ignoring
leap seconds.
The algorithm to convert a
number to a string, given a number input,
is as follows: Return a valid normalized local date
and time string that represents the date and time that is
input milliseconds after midnight on the morning
of 1970-01-01 (the time represented by the value "1970-01-01T00:00:00.0
").
See the note on historical dates in the Date and Time state section.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
readonly
,
required
, and
step
content attributes;
list
,
value
, and
valueAsNumber
IDL attributes;
stepDown()
and
stepUp()
methods.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
size
,
src
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
files
,
selectionStart
,
selectionEnd
,
selectionDirection
, and
valueAsDate
IDL attributes;
select()
,
setRangeText()
, and
setSelectionRange()
methods.
The following example shows part of a flight booking
application. The application uses an input
element
with its type
attribute set to
datetime-local
,
and it then interprets the given date and time in the time zone of
the selected airport.
<fieldset> <legend>Destination</legend> <p><label>Airport: <input type=text name=to list=airports></label></p> <p><label>Departure time: <input type=datetime-local name=totime step=3600></label></p> </fieldset> <datalist id=airports> <option value=ATL label="Atlanta"> <option value=MEM label="Memphis"> <option value=LHR label="London Heathrow"> <option value=LAX label="Los Angeles"> <option value=FRA label="Frankfurt"> </datalist>
If the application instead used the datetime
type, then the
user would have to work out the time-zone conversions himself,
which is clearly not a good user experience!
type=number
)The input
element represents a control
for setting the element's value to a string representing a
number.
If the element is mutable, the user agent should allow the user to change the number represented by its value, as obtained from applying the rules for parsing floating-point number values to it. User agents must not allow the user to set the value to a non-empty string that is not a valid floating-point number. If the user agent provides a user interface for selecting a number, then the value must be set to the best representation of the number representing the user's selection as a floating-point number. User agents should allow the user to set the value to the empty string.
This specification does not define what user interface user agents are to use; user agent vendors are encouraged to consider what would best serve their users' needs. For example, a user agent in Persian or Arabic markets might support Persian and Arabic numeric input (converting it to the format required for submission as described above).
The value
attribute, if
specified and not empty, must have a value that is a valid
floating-point number.
The value sanitization algorithm is as follows: If the value of the element is not a valid floating-point number, then set it to the empty string instead.
The min
attribute, if
specified, must have a value that is a valid floating-point
number. The max
attribute, if specified, must have a value that is a valid
floating-point number.
The step scale factor is
1. The default
step is 1 (allowing only integers, unless the min
attribute has a non-integer
value).
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest number for which the element would not suffer from a step mismatch. If there are two such numbers, user agents are encouraged to pick the one nearest positive infinity.
The algorithm to convert a string to a number, given a string input, is as follows: If applying the rules for parsing floating-point number values to input results in an error, then return an error; otherwise, return the resulting number.
The algorithm to convert a number to a string, given a number input, is as follows: Return a valid floating-point number that represents input.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
,
placeholder
,
readonly
,
required
, and
step
content attributes;
list
,
value
, and
valueAsNumber
IDL attributes;
stepDown()
and
stepUp()
methods.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
size
,
src
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
files
,
selectionStart
,
selectionEnd
,
selectionDirection
, and
valueAsDate
IDL attributes;
select()
,
setRangeText()
, and
setSelectionRange()
methods.
Here is an example of using a numeric input control:
<label>How much do you want to charge? $<input type=number min=0 step=0.01 name=price></label>
The type=number
state is not
appropriate for input that happens to only consist of numbers but
isn't strictly speaking a number. For example, it would be
inappropriate for credit card numbers or US postal codes. A simple
way of determining whether to use type=number
is to consider whether it would make sense for the input control to
have a spinbox interface (e.g. with "up" and "down" arrows). Getting
a credit card number wrong by 1 in the last digit isn't a minor
mistake, it's as wrong as getting every digit incorrect. So it would
not make sense for the user to select a credit card number using
"up" and "down" buttons. When a spinbox interface is not
appropriate, type=text
is probably the right
choice (possibly with a pattern
attribute).
type=range
)The input
element represents a control
for setting the element's value to a string representing a
number, but with the caveat that the exact value is not important,
letting UAs provide a simpler interface than they do for the Number state.
In this state, the range and step constraints are enforced even during user input, and there is no way to set the value to the empty string.
If the element is mutable, the user agent should allow the user to change the number represented by its value, as obtained from applying the rules for parsing floating-point number values to it. User agents must not allow the user to set the value to a string that is not a valid floating-point number. If the user agent provides a user interface for selecting a number, then the value must be set to a best representation of the number representing the user's selection as a floating-point number. User agents must not allow the user to set the value to the empty string.
The value
attribute, if
specified, must have a value that is a valid floating-point
number.
The value sanitization algorithm is as follows: If the value of the element is not a valid floating-point number, then set it to a valid floating-point number that represents the default value.
The min
attribute, if
specified, must have a value that is a valid floating-point
number. The default
minimum is 0. The max
attribute, if specified, must have a value that is a valid
floating-point number. The default maximum is 100.
The default value is the minimum plus half the difference between the minimum and the maximum, unless the maximum is less than the minimum, in which case the default value is the minimum.
When the element is suffering from an underflow, the user agent must set the element's value to a valid floating-point number that represents the minimum.
When the element is suffering from an overflow, if the maximum is not less than the minimum, the user agent must set the element's value to a valid floating-point number that represents the maximum.
The step scale factor is
1. The default
step is 1 (allowing only integers, unless the min
attribute has a non-integer
value).
When the element is suffering from a step mismatch, the user agent must round the element's value to the nearest number for which the element would not suffer from a step mismatch, and which is greater than or equal to the minimum, and, if the maximum is not less than the minimum, which is less than or equal to the maximum. If two numbers match these constraints, then user agents must use the one nearest to positive infinity.
For example, the markup
<input type="range" min=0 max=100 step=20 value=50>
results in a range control whose initial value is 60.
The algorithm to convert a string to a number, given a string input, is as follows: If applying the rules for parsing floating-point number values to input results in an error, then return an error; otherwise, return the resulting number.
The algorithm to convert a number to a string, given a number input, is as follows: Return a valid floating-point number that represents input.
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
,
list
,
max
,
min
, and
step
content attributes;
list
,
value
, and
valueAsNumber
IDL attributes;
stepDown()
and
stepUp()
methods.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
maxlength
,
multiple
,
pattern
,
placeholder
,
readonly
,
required
,
size
,
src
, and
width
.
The following IDL attributes and methods do not apply to the
element:
checked
,
files
,
selectionStart
,
selectionEnd
,
selectionDirection
, and
valueAsDate
IDL attributes;
select()
,
setRangeText()
, and
setSelectionRange()
methods.
Here is an example of a range control using an autocomplete list
with the list
attribute. This
could be useful if there are values along the full range of the
control that are especially important, such as preconfigured light
levels or typical speed limits in a range control used as a speed
control. The following markup fragment:
<input type="range" min="-100" max="100" value="0" step="10" name="power" list="powers"> <datalist id="powers"> <option value="0"> <option value="-30"> <option value="30"> <option value="+50"> </datalist>
...with the following style sheet applied:
input { height: 75px; width: 49px; background: #D5CCBB; color: black; }
...might render as:
Note how the UA determined the orientation of the control from
the ratio of the style-sheet-specified height and width properties.
The colors were similarly derived from the style sheet. The tick
marks, however, were derived from the markup. In particular, the
step
attribute has not
affected the placement of tick marks, the UA deciding to only use
the author-specified completion values and then adding longer tick
marks at the extremes.
Note also how the invalid value +50
was
completely ignored.
For another example, consider the following markup fragment:
<input name=x type=range min=100 max=700 step=9.09090909 value=509.090909>
A user agent could display in a variety of ways, for instance:
Or, alternatively, for instance:
The user agent could pick which one to display based on the dimensions given in the style sheet. This would allow it to maintain the same resolution for the tick marks, despite the differences in width.
type=color
)The input
element represents a color
well control, for setting the element's value to a string representing a
simple color.
In this state, there is always a color picked, and there is no way to set the value to the empty string.
If the element is mutable, the user agent should allow the user to change the color represented by its value, as obtained from applying the rules for parsing simple color values to it. User agents must not allow the user to set the value to a string that is not a valid lowercase simple color. If the user agent provides a user interface for selecting a color, then the value must be set to the result of using the rules for serializing simple color values to the user's selection. User agents must not allow the user to set the value to the empty string.
The value
attribute, if
specified and not empty, must have a value that is a valid
simple color.
The value sanitization algorithm is as
follows: If the value
of the element is a valid simple color, then set it to
the value of the element
converted to ASCII lowercase; otherwise, set it to the string
"#000000
".
The following common input
element content
attributes, IDL attributes, and methods apply to the element:
autocomplete
and
list
content attributes;
list
and
value
IDL attributes.
The value
IDL attribute is
in mode value.
The input
and change
events apply.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
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
,
selectionStart
,
selectionEnd
,
selectionDirection
,
valueAsDate
, and
valueAsNumber
IDL attributes;
select()
,
setRangeText()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
type=checkbox
)The input
element represents a
two-state control that represents the element's checkedness state. If the
element's checkedness state
is true, the control represents a positive selection, and if it is
false, a negative selection. If the element's indeterminate
IDL attribute
is set to true, then the control's selection should be obscured as
if the control was in a third, indeterminate, state.
The control is never a true tri-state control, even
if the element's indeterminate
IDL attribute
is set to true. The indeterminate
IDL attribute
only gives the appearance of a third state.
If the element is mutable,
then: The pre-click activation steps consist of setting
the element's checkedness to
its opposite value (i.e. true if it is false, false if it is true),
and of setting the element's indeterminate
IDL attribute
to false. The canceled activation steps consist of
setting the checkedness and
the element's indeterminate
IDL attribute
back to the values they had before the pre-click activation
steps were run. The activation behavior is to
fire a simple event that bubbles named change
at the element.
If the element is immutable, it has no activation behavior.
Constraint validation: If the element is required and its checkedness is false, then the element is suffering from being missing.
indeterminate
[ = value ]When set, overrides the rendering of checkbox controls so that the current value is not visible.
The following common input
element content
attributes and IDL attributes apply to the element:
checked
, and
required
content attributes;
checked
and
value
IDL attributes.
The value
IDL attribute is
in mode default/on.
The change
event applies.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
autocomplete
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
list
,
max
,
maxlength
,
min
,
multiple
,
pattern
,
placeholder
,
readonly
,
size
,
src
,
step
, and
width
.
The following IDL attributes and methods do not apply to the
element:
files
,
list
,
selectionStart
,
selectionEnd
,
selectionDirection
,
valueAsDate
, and
valueAsNumber
IDL attributes;
select()
,
setRangeText()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
The input
event does not apply.
type=radio
)When an input
element's type
attribute is in the Radio Button state, the rules
in this section apply.
The input
element represents a control
that, when used in conjunction with other input
elements, forms a radio button group in which only one
control can have its checkedness state set to true. If
the element's checkedness
state is true, the control represents the selected control in the
group, and if it is false, it indicates a control in the group that
is not selected.
The radio button group that contains an
input
element a also contains all
the other input
elements b that
fulfill all of the following conditions:
input
element b's type
attribute is in the Radio Button state.name
attribute, their name
attributes
are not empty, and the value of a's name
attribute is a compatibility
caseless match for the value of b's
name
attribute.A document must not contain an input
element whose
radio button group contains only that element.
When any of the following phenomena occur, if the element's checkedness state is true after the occurrence, the checkedness state of all the other elements in the same radio button group must be set to false:
name
attribute
is set, changed, or removed.If the element is mutable,
then: The pre-click activation steps consist of setting
the element's checkedness to
true. The canceled activation steps consist of setting
the element's checkedness to
false. The activation behavior is to fire a
simple event that bubbles named change
at the element. .
If the element is immutable, it has no activation behavior.
Constraint validation: If an element in the
radio button group is required, and all of the
input
elements in the radio button group have a
checkedness that is false,
then the element is suffering from being missing.
If none of the radio buttons in a radio button group are checked when they are inserted into the document, then they will all be initially unchecked in the interface, until such time as one of them is checked (either by the user or by script).
The following common input
element content
attributes and IDL attributes apply to the element:
checked
and
required
content attributes;
checked
and
value
IDL attributes.
The value
IDL attribute is
in mode default/on.
The change
event applies.
The following content attributes must not be specified and do not
apply to the element:
accept
,
alt
,
autocomplete
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
list
,
max
,
maxlength
,
min
,
multiple
,
pattern
,
placeholder
,
readonly
,
size
,
src
,
step
, and
width
.
The following IDL attributes and methods do not apply to the
element:
files
,
list
,
selectionStart
,
selectionEnd
,
selectionDirection
,
valueAsDate
, and
valueAsNumber
IDL attributes;
select()
,
setRangeText()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
The input
event does not apply.
type=file
)When an input
element's type
attribute is in the File Upload state, the rules in this
section apply.
The input
element represents a list of
selected files,
each file consisting of a file name, a file type, and a file body
(the contents of the file).
File names may contain partial paths, e.g. in the case that a user has selected an entire directory hierarchy. Path components should be separated from each other using "\" (U+005C) character.
If the element is mutable, the user agent should allow the user to change the files on the list, e.g. adding or removing files. Files can be from the filesystem or created on the fly, e.g. a picture taken from a camera connected to the user's device.
Constraint validation: If the element is required and the list of selected files is empty, then the element is suffering from being missing.
Unless the multiple
attribute is set, there must be no more than one file in the list of
selected
files.
The accept
attribute may be specified to provide user agents with a hint of
what file types will be accepted.
If specified, the attribute must consist of a set of comma-separated tokens, each of which must be an ASCII case-insensitive match for one of the following:
audio/*
video/*
image/*
The tokens must not be ASCII case-insensitive matches for any of the other tokens (i.e. duplicates are not allowed). To obtain the list of tokens from the attribute, the user agent must split the attribute value on commas.
User agents may use the value of this attribute to display a more
appropriate user interface than a generic file picker. For instance,
given the value image/*
, a user agent could
offer the user the option of using a local camera or selecting a
photograph from their photo collection; given the value audio/*
, a user agent could offer the user the
option of recording a clip using a headset microphone.
User agents should prevent the user from selecting files that are not accepted by one (or more) of these tokens.
Authors are encouraged to specify both any MIME types and any corresponding extensions when looking for data in a specific format.
For example, consider an application that converts Microsoft Word documents to Open Document Format files. Since Microsoft Word documents are described with a wide variety of MIME types and extensions, the site can list several, as follows:
<input type="file" accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document">
On platforms that only use file extensions to describe file types, the extensions listed here can be used to filter the allowed documents, while the MIME types can be used with the system's type registration table (mapping MIME types to extensions used by the system), if any, to determine any other extensions to allow. Similarly, on a system that does not have file names or extensions but labels documents with MIME types internally, the MIME types can be used to pick the allowed files, while the extensions can be used if the system has an extension registration table that maps known extensions to MIME types used by the system.
Extensions tend to be ambiguous (e.g. there are
an untold number of formats that use the ".dat
" extension, and users can typically quite
easily rename their files to have a ".doc
"
extension even if they are not Microsoft Word documents), and MIME
types tend to be unreliable (e.g. many formats have no formally
registered types, and many formats are in practice labeled using a
number of different MIME types). Authors are reminded that, as
usual, data received from a client should be treated with caution,
as it may not be in an expected format even if the user is not
hostile and the user agent fully obeyed the accept
attribute's
requirements.
For historical reasons, the value
IDL attribute prefixes the
filename with the string "C:\fakepath\
". Some
legacy user agents actually included the full path (which was a
security vulnerability). As a result of this, obtaining the
filename from the value
IDL
attribute in a backwards-compatible way is non-trivial. The
following function extracts the filename in a suitably compatible
manner:
function extractFilename(path) { if (path.substr(0, 12) == "C:\\fakepath\\") return path.substr(12); // modern browser var x; x = path.lastIndexOf('/'); if (x >= 0) // Unix-based path return path.substr(x+1); x = path.lastIndexOf('\\'); if (x >= 0) // Windows-based path return path.substr(x+1); return path; // just the filename }
This can be used as follows:
<p><input type=file name=image onchange="updateFilename(this.value)"></p> <p>The name of the file you picked is: <span id="filename">(none)</span></p> <script> function updateFilename(path) { var name = extractFilename(path); document.getElementById('filename').textContent = name; } </script>
The following common input
element content
attributes apply to the element:
The following common input
element content
attributes and IDL attributes apply to the element:
accept
,
multiple
, and
required
;
files
and
value
IDL attributes.
The value
IDL attribute is
in mode filename.
The change
event applies.
The following content attributes must not be specified and do not
apply to the element:
alt
,
autocomplete
,
checked
,
dirname
,
formaction
,
formenctype
,
formmethod
,
formnovalidate
,
formtarget
,
height
,
list
,
max
,
maxlength
,
min
,
pattern
,
placeholder
,
readonly
,
size
,
src
,
step
, and
width
.
The element's value
attribute must be omitted.
The following IDL attributes and methods do not apply to the
element:
checked
,
list
,
selectionStart
,
selectionEnd
,
selectionDirection
,
valueAsDate
, and
valueAsNumber
IDL attributes;
select()
,
setRangeText()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
The input
event does not apply.
type=submit
)When an input
element's type
attribute is in the Submit Button state, the rules
in this section apply.
The input
element represents a button
that, when activated, submits the form. If the
element has a value
attribute,
the button's label must be the value of that attribute; otherwise,
it must be an implementation-defined string that means "Submit" or
some such. The element is a button, specifically a submit button.
If the element is mutable,
then the element's activation behavior is as follows:
if the element has a form owner, submit the form
owner from the input
element; otherwise, do
nothing.
If the element is immutable, it has no activation behavior.
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 following common input
element content
attributes and IDL attributes apply to the element:
formaction
,
formenctype
,
formmethod
,
formnovalidate
, and
formtarget
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
,
alt
,
autocomplete
,
checked
,
dirname
,
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
,
selectionStart
,
selectionEnd
,
selectionDirection
,
valueAsDate
, and
valueAsNumber
IDL attributes;
select()
,
setRangeText()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
type=image
)When an input
element's type
attribute is in the Image Button state, the rules
in this section apply.
The input
element represents either an
image from which a user can select a coordinate and submit the form,
or alternatively a button from which the user can submit the
form. The element is a button,
specifically a submit
button.
The coordinate is sent to the server during form submission
by sending two entries for the element, derived from the name of the
control but with ".x
" and ".y
" appended to the name with the x and y components of the
coordinate respectively.
The image is given by the src
attribute. The src
attribute must be present, and
must contain a valid non-empty URL potentially surrounded by
spaces referencing a non-interactive, optionally animated,
image resource that is neither paged nor scripted.
When any of the following events occur, unless the user agent
cannot support images, or its support for images has been disabled,
or the user agent only fetches elements on demand, or the src
attribute's value is the empty
string, the user agent must resolve the value of the src
attribute, relative to the
element, and if that is successful, must
fetch the resulting absolute
URL:
input
element's type
attribute is first set to the
Image Button state
(possibly when the element is first created), and the src
attribute is present.input
element's type
attribute is changed back to
the Image Button state,
and the src
attribute is
present, and its value has changed since the last time the type
attribute was in the Image Button state.input
element's type
attribute is in the Image Button state, and the
src
attribute is set or
changed.Fetching the image must delay the load event of the element's document until the task that is queued by the networking task source once the resource has been fetched (defined below) has been run.
If the image was successfully obtained, with no network errors, and the image's type is a supported image type, and the image is a valid image of that type, then the image is said to be available. If this is true before the image is completely downloaded, each task that is queued by the networking task source while the image is being fetched must update the presentation of the image appropriately.
The user agents should apply the image sniffing rules to determine the type of the image, with the image's associated Content-Type headers giving the official type. If these rules are not applied, then the type of the image must be the type given by the image's associated Content-Type headers.
User agents must not support non-image resources with the
input
element. User agents must not run executable code
embedded in the image resource. User agents must only display the
first page of a multipage resource. User agents must not allow the
resource to act in an interactive fashion, but should honor any
animation in the resource.
The task that is queued by the networking task
source once the resource has been fetched, must, if the download was successful
and the image is available,
queue a task to fire a simple event named
load
at the input
element; and otherwise, if the fetching process fails without a
response from the remote server, or completes but the image is not a
valid or supported image, queue a task to fire a
simple event named error
on
the input
element.
The alt
attribute
provides the textual label for the button for users and user agents
who cannot use the image. The alt
attribute must be present, and
must contain a non-empty string.
The input
element supports dimension
attributes.
If the src
attribute is set,
and the image is available and
the user agent is configured to display that image, then: The
element represents a control for selecting a coordinate from
the image specified by the src
attribute; if the element is mutable, the user agent should
allow the user to select this coordinate, and
the element's activation behavior is as follows: if the
element has a form owner, take the user's selected
coordinate,
and submit 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, then the element's
activation behavior is as follows: if the element has a
form owner, set the selected
coordinate to (0,0), and submit the input
element's form owner from the input
element.
In either case, if the element is mutable but has no form owner, then its activation behavior must be to do nothing. If the element is immutable, it has no activation behavior.
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.
width
[ = value ]height
[ = value ]These attributes return the actual rendered dimensions of the image, or zero if the dimensions are not known.
They can be set, to change the corresponding content attributes.
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
,
dirname
,
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
,
selectionStart
,
selectionEnd
,
selectionDirection
,
valueAsDate
, and
valueAsNumber
IDL attributes;
select()
,
setRangeText()
,
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.
Take the following form:
<form action="process.cgi"> <input type=image src=map.png name=where> </form>
If the user clicked on the image at coordinate (127,40) then the
URL used to submit the form would be "process.cgi?where.x=127&where.y=40
".
type=reset
)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, then the element's activation behavior, if the element has a form owner, is to reset the form owner; otherwise, it is to do nothing.
If the element is immutable, it has no activation behavior.
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
,
dirname
,
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
,
selectionStart
,
selectionEnd
,
selectionDirection
,
valueAsDate
, and
valueAsNumber
IDL attributes;
select()
,
setRangeText()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
type=button
)The input
element represents a button
with no default behavior. A label for the button must be provided in
the value
attribute, though it
may be the empty string. 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 element's activation behavior is to do nothing.
If the element is immutable, it has no activation behavior.
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
,
dirname
,
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
,
selectionStart
,
selectionEnd
,
selectionDirection
,
valueAsDate
, and
valueAsNumber
IDL attributes;
select()
,
setRangeText()
,
setSelectionRange()
,
stepDown()
, and
stepUp()
methods.
This section is non-normative.
The formats shown to the user in date, time, and number controls is independent of the format used for form submission.
Browsers are encouraged to use user interfaces that present
dates, times, and numbers according to the conventions of either the
locale implied by the input
element's
language or the user's preferred locale. Using the
page's locale will ensure consistency with page-provided data.
For example, it would be confusing to users if an American English page claimed that a Cirque De Soleil show was going to be showing on 02/03, but their browser, configured to use the British English locale, only showed the date 03/02 in the ticket purchase date picker. Using the page's locale would at least ensure that the date was presented in the same format everywhere. (There's still a risk that the user would end up arriving a month late, of course, but there's only so much that can be done about such cultural differences...)
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, user agents should not allow users to trivially override the resulting autocompletion state to on, as there are significant security implications for the user if all values are always remembered, regardless of the site's preferences.
dirname
attributeThe dirname
attribute, when it applies, is a form control dirname
attribute.
In this example, a form contains a text field and a submission button:
<form action="addcomment.cgi" method=post> <p><label>Comment: <input type=text name="comment" dirname="comment.dir" required></label></p> <p><button name="mode" type=submit value="add">Post Comment</button></p> </form>
When the user submits the form, the user agent includes three fields, one called "comment", one called "comment.dir", and one called "mode"; so if the user types "Hello", the submission body might be something like:
comment=Hello&comment.dir=ltr&mode=add
If the user manually switches to a right-to-left writing direction and enters "مرحبًا", the submission body might be something like:
comment=%D9%85%D8%B1%D8%AD%D8%A8%D9%8B%D8%A7&comment.dir=rtl&mode=add
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.
How user selections of suggestions are handled depends on whether the element is a control accepting a single value only, or whether it accepts multiple values:
multiple
attribute specified or
if the multiple
attribute
does not applyWhen the user selects a suggestion, the input
element's value must be set
to the selected suggestion's value, as if the user had
written that value himself.
multiple
attribute specified,
and the multiple
attribute
does applyWhen the user selects a suggestion, the user agent must either
add a new entry to the input
element's values, whose value is
the selected suggestion's value, or change an existing
entry in the input
element's values to have the value
given by the selected suggestion's value, as if the user had
himself added an entry with that value, or edited an existing
entry to be that value. Which behavior is to be applied depends on
the user interface in a user-agent-defined manner.
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
need to 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 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 user 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.
The difference between disabled
and readonly
is that read-only
controls are still focusable, so the user can still select the text
and interact with it, whereas disabled controls are entirely
non-interactive. (For this reason, only text controls can be made
read-only: it wouldn't make sense for checkboxes or buttons, for
instances.)
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="readonly" name="1.pid" value="H412"> <td> <input required="required" name="1.pname" value="Floor lamp Ulke"> <td> $<input required="required" type="number" min="0" step="0.01" name="1.pprice" value="49.99"> <td> <button formnovalidate="formnovalidate" name="action" value="delete:1">Delete</button> <tr> <td> <input readonly="readonly" name="2.pid" value="FG28"> <td> <input required="required" name="2.pname" value="Table lamp Ulke"> <td> $<input required="required" type="number" min="0" step="0.01" name="2.pprice" value="24.99"> <td> <button formnovalidate="formnovalidate" name="action" value="delete:2">Delete</button> <tr> <td> <input required="required" name="3.pid" value="" pattern="[A-Z0-9]+"> <td> <input required="required" name="3.pname" value=""> <td> $<input required="required" type="number" min="0" step="0.01" name="3.pprice" value=""> <td> <button formnovalidate="formnovalidate" name="action" value="delete:3">Delete</button> </table> <p> <button formnovalidate="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 and has a default value of 20.
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 considered 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 oninput="up2.setCustomValidity(up2.value != up.value ? 'Passwords do not match.' : '')"> <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 name=up2> <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-unit 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 conversation through this medium to be terse and discouraging intelligent discourse.
<label>What are you doing? <input name=status maxlength=140></label>
pattern
attributeThe pattern
attribute specifies a regular expression against which the control's
value, or, when the multiple
attribute applies and is
set, the control's values, are to be
checked.
If specified, the attribute's value must match the JavaScript Pattern production. [ECMA262]
If an input
element has a pattern
attribute 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, then the resulting
regular expression is the element's compiled pattern regular
expression. If the element has no such attribute, or if the
value doesn't compile successfully, then the element has no
compiled pattern regular expression. [ECMA262]
Constraint validation: If the element's value is not the empty string, and
either the element's multiple
attribute is not
specified or it does not apply to the input
element
given its type
attribute's
current state, and the element has a compiled pattern regular
expression but that regular expression does not match the
entirety of the element's value, then the element is
suffering from a pattern mismatch.
Constraint validation: If the element's value is not the empty string, and
the element's multiple
attribute is specified and applies to the input
element, and the element has a compiled pattern regular
expression but that regular expression does not match the
entirety of each of the element's values, then the element
is suffering from a pattern mismatch.
The compiled pattern regular expression, when matched against a string, must have its start anchored to the start of the string and its end anchored to the end of the string.
This implies that the regular expression language
used for this attribute is the same as that used in JavaScript,
except that the pattern
attribute is matched against 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 submit this form when the field is incorrect.
When a control has a pattern
attribute, the title
attribute, if used, must describe
the pattern. Additional information could also be included, so long
as it assists the user in filling in the control. Otherwise,
assistive technology would be impaired.
For instance, if the title attribute contained the caption of the control, assistive technology could end up saying something like The text you have entered does not match the required pattern. Birthday, which is not useful.
UAs may still show the title
in
non-error situations (for example, as a tooltip when hovering over
the control), so authors should be careful not to word title
s as if an error has necessarily
occurred.
min
and max
attributesThe min
and max
attributes indicate
the allowed range of values for the element.
Their syntax is defined by the section that defines the type
attribute's current state.
If the element has a min
attribute, and the result of applying the algorithm to convert a
string to a number to the value of the min
attribute is a number, then that
number is the element's minimum; otherwise, if the type
attribute's current state
defines a default
minimum, then that is the minimum; otherwise, the element has
no minimum.
Constraint validation: When the element has a minimum, and the result of applying the algorithm to convert a string to a number to the string given by the element's value is a number, and the number obtained from that algorithm is less than the minimum, the element is suffering from an underflow.
The min
attribute also
defines the step
base.
If the element has a max
attribute, and the result of applying the algorithm to convert a
string to a number to the value of the max
attribute is a number, then that
number is the element's maximum; otherwise, if the type
attribute's current state
defines a default
maximum, then that is the maximum; otherwise, the element has
no maximum.
Constraint validation: When the element has a maximum, and the result of applying the algorithm to convert a string to a number to the string given by the element's value is a number, and the number obtained from that algorithm is more than the maximum, the element is suffering from an overflow.
The max
attribute's value
(the maximum) must not be
less than the min
attribute's
value (its minimum).
If an element has a maximum that is less than its minimum, then so long as the element has a value, it will either be suffering from an underflow or suffering from an overflow.
An element has range limitations if it has a defined minimum or a defined maximum.
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, the step scale
factor, and in some cases the default step base,
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 the default step
base, if one is defined, or zero, if not.
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 when the control has no
value. 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 "LF" (U+000A) or "CR" (U+000D)
characters.
The placeholder
attribute should not be used as an alternative to a
label
. For a longer hint or other advisory text, the
title
attribute is more
appropriate.
These mechanisms are very similar but subtly
different: the hint given by the control's label
is
shown at all times; the short hint given in the placeholder
attribute is shown
before the user enters a value; and the hint in the title
attribute is shown when the user
requests further help.
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/or the control is not focused (e.g. by displaying it inside a blank unfocused control and hiding it otherwise).
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>
In situations where the control's content has one directionality but the placeholder needs to have a different directionality, Unicode's bidirectional-algorithm formatting characters can be used in the attribute value:
<input name=t1 type=tel placeholder="‫ رقم الهاتف 1 ‮"> <input name=t2 type=tel placeholder="‫ رقم الهاتف 2 ‮">
For slightly more clarity, here's the same example using numeric character references instead of inline Arabic:
<input name=t1 type=tel placeholder="‫رقم الهاتف 1‮"> <input name=t2 type=tel placeholder="‫رقم الهاتف 2‮">
input
element APIsvalue
[ = value ]Returns the current value of the form control.
Can be set, to change the value.
Throws an InvalidStateError
exception if it is
set to any value other than the empty string when the control is a
file upload control.
checked
[ = value ]Returns the current checkedness of the form control.
Can be set, to change the checkedness.
files
Returns a FileList
object listing the selected files of
the form control.
Returns null if the control isn't a file control.
valueAsDate
[ = value ]Returns a Date
object representing the form
control's value, if
applicable; otherwise, returns null.
Can be set, to change the value.
Throws an InvalidStateError
exception if the
control isn't date- or time-based.
valueAsNumber
[ = value ]Returns a number representing the form control's value, if applicable; otherwise, returns NaN.
Can be set, to change the value.
Throws an InvalidStateError
exception if the
control is neither date- or time-based nor numeric.
stepUp
( [ n ] )stepDown
( [ n ] )Changes the form control's value by the value given in the
step
attribute, multiplied by
n. The default value for n
is 1.
Throws InvalidStateError
exception if the control
is neither date- or time-based nor numeric, if the step
attribute's value is "any
", if the current value could not be parsed, or if
stepping in the given direction by the given amount would take the
value out of range.
list
Returns the datalist
element indicated by the
list
attribute.
The value
IDL
attribute allows scripts to manipulate the value of an input
element. The attribute is in one of the following modes, which
define its behavior:
On getting, it must return the current value of the element. On setting,
it must set the element's value to the new value, set the
element's dirty value
flag to true, invoke the value sanitization
algorithm, if the element's type
attribute's current state
defines one, and then, if the element has a text entry cursor
position, should move the text entry cursor position to the end of
the text field, unselecting any selected text and resetting the
selection direction to none.
On getting, if the element has a value
attribute, it must return
that attribute's value; otherwise, it must return the empty
string. On setting, it must set the element's value
attribute to the new
value.
On getting, if the element has a value
attribute, it must return
that attribute's value; otherwise, it must return the string
"on
". On setting, it must set the element's
value
attribute to the new
value.
On getting, it must return the string "C:\fakepath\
" followed by the filename of the
first file in the list of selected files, if
any, or the empty string if the list is empty. On setting, if the
new value is the empty string, it must empty the list of selected files;
otherwise, it must throw an InvalidStateError
exception.
This "fakepath" requirement is a sad accident of history. See the example in the File Upload state section for more information.
The checked
IDL
attribute allows scripts to manipulate the checkedness of an
input
element. On getting, it must return the current
checkedness of the element;
and on setting, it must set the element's checkedness to the new value and
set the element's dirty checkedness
flag to true.
The files
IDL
attribute allows scripts to access the element's selected files. On
getting, if the IDL attribute applies, it must return a
FileList
object that represents the current selected files. The
same object must be returned until the list of selected files
changes. If the IDL attribute does not apply, then it must instead
return null. [FILEAPI]
The valueAsDate
IDL
attribute represents the value of the element, interpreted
as a date.
On getting, if the valueAsDate
attribute does not
apply, as defined for the input
element's type
attribute's current state, then
return null. Otherwise, run the algorithm to convert a
string to a Date
object defined for that state;
if the algorithm returned a Date
object, then return
it, otherwise, return null.
On setting, if the valueAsDate
attribute does not
apply, as defined for the input
element's type
attribute's current state, then
throw an InvalidStateError
exception; otherwise, if the
new value is null or a Date
object representing the NaN
time value, then set the value
of the element to the empty string; otherwise, run the algorithm to convert a
Date
object to a string, as defined for that
state, on the new value, and set the value of the element to resulting
string.
The valueAsNumber
IDL
attribute represents the value
of the element, interpreted as a number.
On getting, if the valueAsNumber
attribute does
not apply, as defined for the input
element's type
attribute's current state, then
return a Not-a-Number (NaN) value. Otherwise, if the valueAsDate
attribute applies, run the algorithm to convert a
string to a Date
object defined for that state;
if the algorithm returned a Date
object, then return
the time value of the object (the number of milliseconds from
midnight UTC the morning of 1970-01-01 to the time represented by
the Date
object), otherwise, return a Not-a-Number
(NaN) value. Otherwise, run the algorithm to convert a
string to a number defined for that state; if the algorithm
returned a number, then return it, otherwise, return a Not-a-Number
(NaN) value.
On setting, if the valueAsNumber
attribute does
not apply, as defined for the input
element's type
attribute's current state, then
throw an InvalidStateError
exception. Otherwise, if
the valueAsDate
attribute applies, run the algorithm to convert a
Date
object to a string defined for that state,
passing it a Date
object whose time value is the
new value, and set the value
of the element to resulting string. Otherwise, run the algorithm to convert a
number to a string, as defined for that state, on the new
value, and set the value of
the element to resulting string.
The stepDown(n)
and stepUp(n)
methods, when invoked, must run the
following algorithm:
If the stepDown()
and
stepUp()
methods do not
apply, as defined for the input
element's type
attribute's current state, then
throw an InvalidStateError
exception, and abort these
steps.
If the element has no allowed value step, then throw an
InvalidStateError
exception, and abort these
steps.
If applying the algorithm to convert a
string to a number to the string given by the element's
value results in an error,
then throw an InvalidStateError
exception, and abort
these steps; otherwise, let value be the result
of that algorithm.
Let n be the argument, or 1 if the argument was omitted.
Let delta be the allowed value step multiplied by n.
If the method invoked was the stepDown()
method, negate delta.
Let value be the result of adding delta to value.
If the element has a minimum, and the value is less than that minimum, then throw a
InvalidStateError
exception.
If the element has a maximum, and the value is greater than that maximum, then throw a
InvalidStateError
exception.
Let value as string be the result of
running the algorithm to convert a
number to a string, as defined for the input
element's type
attribute's
current state, on value.
Set the value of the element to value as string.
The list
IDL
attribute must return the current suggestions source element, if
any, or null otherwise.
When the input
event applies, any time the user causes the element's value to change, the user agent must
queue a task to fire a simple event that
bubbles named input
at the
input
element. User agents may wait for a suitable
break in the user's interaction before queuing the task; for
example, a user agent could wait for the user to have not hit a key
for 100ms, so as to only fire the event when the user pauses,
instead of continuously for each keystroke.
Examples of a user changing the element's value would include the user typing into a text field, pasting a new value into the field, or undoing an edit in that field. Some user interactions do not cause changes to the value, e.g. hitting the "delete" key in an empty text field, or replacing some text in the field with text from the clipboard that happens to be exactly the same text.
When the change
event applies,
if the element does not have an activation behavior
defined but uses a user interface that involves an explicit commit
action, then any time the user commits a change to the element's
value or list of selected files, the
user agent must queue a task to fire a simple
event that bubbles named change
at the input
element.
An example of a user interface with a commit action would be a File Upload control that consists of a single button that brings up a file selection dialog: when the dialog is closed, if that the file selection changed as a result, then the user has committed a new file selection.
Another example of a user interface with a commit action would be a Date control that allows both text-based user input and user selection from a drop-down calendar: while text input might not have an explicit commit step, selecting a date from the drop down calendar and then dismissing the drop down would be a commit action.
When the user agent changes the element's value on behalf of the user (e.g. as part of a form prefilling feature), the user agent must follow these steps:
input
event
applies, queue a task to fire a simple
event that bubbles named input
at the input
element.change
event
applies, queue a task to fire a simple
event that bubbles named change
at the input
element.In addition, when the change
event applies, change
events can also be fired as part
of the element's activation behavior and as part of the
unfocusing steps.
The task source for these tasks is the user interaction task source.
button
elementautofocus
disabled
form
formaction
formenctype
formmethod
formnovalidate
formtarget
name
type
value
interface HTMLButtonElement : HTMLElement { attribute boolean autofocus; attribute boolean disabled; readonly attribute HTMLFormElement? form; attribute DOMString formAction; attribute DOMString formEnctype; attribute DOMString formMethod; attribute boolean 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(DOMString error); readonly attribute NodeList labels; };
The button
element represents a button labeled by its contents.
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.
When a button
element is not disabled, its activation
behavior 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
IDL
attribute must reflect the content attribute of the
same name.
The type
IDL
attribute must reflect the content attribute of the
same name, limited to only known values.
The willValidate
, validity
, and validationMessage
IDL
attributes, and the checkValidity()
and setCustomValidity()
methods, are part of the constraint validation API. The
labels
IDL attribute provides a
list of the element's label
s. The autofocus
, disabled
, form
, and name
IDL attributes are part of the
element's forms API.
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.autofocus
disabled
form
multiple
name
required
size
interface HTMLSelectElement : HTMLElement { attribute boolean autofocus; attribute boolean disabled; readonly attribute HTMLFormElement? form; attribute boolean multiple; attribute DOMString name; attribute boolean required; attribute unsigned long size; readonly attribute DOMString type; readonly attribute HTMLOptionsCollection options; attribute unsigned long length; getter Element item(unsigned long index); object namedItem(DOMString name); void add((HTMLOptionElement or HTMLOptGroupElement) element, optional (HTMLElement or long)? before = null); void remove(long index); setter creator void (unsigned long index, HTMLOptionElement? option); 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(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 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.
The display size of a
select
element is the result of applying the
rules for parsing non-negative integers to the value of
element's size
attribute, if
it has one and parsing it is successful. If applying those rules to
the attribute's value is not successful, or if the size
attribute is absent, then the
element's display size is 4
if the element's multiple
content attribute is present, and 1 otherwise.
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 required
attribute is a boolean attribute. When specified, the
user will be required to select a value before submitting the
form.
If a select
element has a required
attribute specified,
does not have a multiple
attribute specified, and has a display size of 1;
and if the value of the
first option
element in the select
element's list of
options (if any) is the empty string, and that
option
element's parent node is the select
element (and not an optgroup
element), then that
option
is the select
element's
placeholder label option.
If a select
element has a required
attribute specified,
does not have a multiple
attribute specified, and has a display size of 1,
then the select
element must have a placeholder
label option.
Constraint validation: If the element has its
required
attribute
specified, and either none of the option
elements in
the select
element's list of options have their
selectedness set to
true, or the only option
element in the
select
element's list of options with its
selectedness set to
true is the placeholder label option, then the element
is suffering from being missing.
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.
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 and the element's display size is greater than 1,
then the user agent should also allow the user to request that the
option
whose selectedness is true, if
any, be unselected. Upon this request being conveyed to the user
agent, and before the relevant user interaction event is queued (e.g. before the click
event), the user agent must set the
selectedness of
that option
element to false 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.
If the multiple
attribute is absent and the element's display size is 1, then 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.
The reset
algorithm for select
elements is to go through
all the option
elements in the element's list of options, and set
their selectedness
to true if the option
element has a selected
attribute, and false
otherwise.
The form
attribute is used to
explicitly associate the select
element with its
form owner. The name
attribute represents the element's name. The disabled
attribute is used to make
the control non-interactive and to prevent its value from being
submitted. The autofocus
attribute controls focus.
type
Returns "select-multiple
" if the element
has a multiple
attribute, and "select-one
"
otherwise.
options
Returns an HTMLOptionsCollection
of the list of options.
length
[ = value ]Returns the number of elements in the list of options.
When set to a smaller number, truncates the number of option
elements in the select
.
When set to a greater number, adds new blank option
elements to the select
.
item
(index)Returns the item with index index from the list of options. The items are sorted in tree order.
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 HierarchyRequestError
exception if element is an ancestor of the
element into which it is to be inserted.
selectedOptions
Returns an HTMLCollection
of the list of options that are
selected.
selectedIndex
[ = value ]Returns the index of the first selected item, if any, or −1 if there is no selected item.
Can be set, to change the selection.
value
[ = value ]Returns the value of the first selected item, if any, or the empty string if there is no selected item.
Can be set, to change the selection.
The type
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
supported property indices at any instant are the
indices 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.
When the user agent is to set the value of a new indexed
property for a given property index index
to a new value value, it must instead set the value of a new
indexed property with the given property index index to the new value value on the
options
collection.
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 the first 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
,
required
, and
size
IDL attributes
must reflect the respective content attributes of the
same name. The size
IDL
attribute has a default value of zero.
For historical reasons, the default value of the
size
IDL attribute does not
return the actual size used, which, in the absence of the size
content attribute, is either 1
or 4 depending on the presence of the multiple
attribute.
The willValidate
, validity
, and validationMessage
IDL
attributes, and the checkValidity()
and setCustomValidity()
methods, are part of the constraint validation API. The
labels
IDL attribute provides a
list of the element's label
s. The autofocus
, disabled
, form
, and name
IDL attributes are part of the
element's forms API.
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>
When there is no default option, a placeholder can be used instead:
<select name="unittype" required> <option value=""> Select unit type </option> <option value="1"> Miner </option> <option value="2"> Puffer </option> <option value="3"> Snipey </option> <option value="4"> Max </option> <option value="5"> Firebot </option> </select>
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>
Sometimes, a user has to select one or more items. This example shows such an interface.
<p>Select the songs from that you would like on your Act II Mix Tape:</p> <select multiple required name="act2"> <option value="s1">It Sucks to Be Me (Reprise) <option value="s2">There is Life Outside Your Apartment <option value="s3">The More You Ruv Someone <option value="s4">Schadenfreude <option value="s5">I Wish I Could Go Back to College <option value="s6">The Money Song <option value="s7">School for Monsters <option value="s8">The Money Song (Reprise) <option value="s9">There's a Fine, Fine Line (Reprise) <option value="s10">What Do You Do With a B.A. in English? (Reprise) <option value="s11">For Now </select>
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.
options
Returns 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.disabled
label
interface HTMLOptGroupElement : HTMLElement { attribute boolean disabled; attribute DOMString label; };
The optgroup
element represents a group of
option
elements with a common label.
The element's group of option
elements consists of
the option
elements that are children of the
optgroup
element.
When showing option
elements in select
elements, user agents should show the option
elements
of such groups as being related to each other and separate from
other option
elements.
The disabled
attribute
is a boolean attribute and can be used to disable a group of
option
elements together.
The label
attribute must be specified. Its value gives the name of the group,
for the purposes of the user interface. User
agents should use this attribute's value when labelling the group of
option
elements in a select
element.
The disabled
and label
attributes must
reflect the respective content attributes of the same
name.
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.disabled
label
selected
value
[NamedConstructor=Option(), NamedConstructor=Option(DOMString text), NamedConstructor=Option(DOMString text, DOMString value), NamedConstructor=Option(DOMString text, DOMString value, boolean defaultSelected), NamedConstructor=Option(DOMString text, DOMString value, boolean defaultSelected, 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.
In certain circumstances described in the definition of the
select
element, an option
element can be a
select
element's placeholder label option.
A placeholder label option does not represent an actual
option, but instead represents a label for the select
control.
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
content attribute, if there
is one, or, if there is not, the value of the element's text
IDL attribute.
The value
attribute provides a value for element. The value of an option
element is the value of the value
content attribute, if there
is one, or, if there is not, the value of the element's text
IDL attribute.
The selected
attribute is a boolean attribute. It represents the
default selectedness of the
element.
The selectedness
of an option
element is a boolean state, initially
false. 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.
A select
element whose multiple
attribute is not
specified must not have more than one descendant option
element with its selected
attribute set.
An option
element's index is the number of
option
element that are in the same list of options but that
come before it in tree order. If the
option
element is not in a list of options, then the
option
element's index is zero.
selected
Returns true if the element is selected, and false otherwise.
Can be set, to override the current state of the element.
index
Returns the index of the element in its select
element's options
list.
form
Returns the element's form
element, if any, or
null otherwise.
text
Same as textContent
, except that spaces are collapsed.
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
IDL attribute must reflect the content attribute of the
same name. The defaultSelected
IDL attribute must reflect the selected
content attribute.
The label
IDL
attribute, on getting, must return the element's label. On setting, the element's
label
content attribute must
be set to the new value.
The value
IDL
attribute, on getting, must return the element's value. On setting, the element's
value
content attribute must
be set to the new value.
The selected
IDL attribute, on getting, must return true if the element's selectedness is true, and
false otherwise. On setting, it must set the element's selectedness to the new
value.
The index
IDL
attribute must return the element's index.
The text
IDL
attribute, on getting, must return the value of the
textContent
IDL attribute on the element, with leading and trailing
whitespace stripped, and with any sequences of two or more
space characters replaced by a
single U+0020 SPACE character. On setting, it 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 an optgroup
element as its parent and that
optgroup
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
Text
node 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
elementautofocus
cols
dirname
disabled
form
maxlength
name
placeholder
readonly
required
rows
wrap
interface HTMLTextAreaElement : HTMLElement { attribute boolean autofocus; attribute unsigned long cols; attribute DOMString dirName; 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; [TreatNullAs=EmptyString] attribute DOMString value; readonly attribute unsigned long textLength; readonly attribute boolean willValidate; readonly attribute ValidityState validity; readonly attribute DOMString validationMessage; boolean checkValidity(); void setCustomValidity(DOMString error); readonly attribute NodeList labels; void select(); attribute unsigned long selectionStart; attribute unsigned long selectionEnd; attribute DOMString selectionDirection; void setSelectionRange(unsigned long start, unsigned long end, optional DOMString direction); };
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 raw value of
a textarea
control must be initially the empty
string.
A newline in a textarea
element, and in its raw value, should separate
paragraphs for the purposes of the Unicode bidirectional algorithm.
This requirement may be implemented indirectly through the style
layer. For example, an HTML+CSS user agent could implement these
requirements by implementing the CSS 'unicode-bidi' property. [BIDI] [CSS]
The readonly
attribute
is a boolean attribute used to control whether the text
can be edited by the user or not.
In this example, a text field is marked read-only because it represents a read-only file:
Filename: <code>/etc/bash.bashrc</code> <textarea name="buffer" readonly> # System-wide .bashrc file for interactive bash(1) shells. # To enable the settings / commands in this file for login shells as well, # this file has to be sourced in /etc/profile. # If not running interactively, don't do anything [ -z "$PS1" ] && return ...</textarea>
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: the user agent should allow the user to edit,
insert, and remove text, and to insert and remove line breaks in the
form of "LF" (U+000A) characters. 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. 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.
If the element is mutable, the user agent should allow the user to change the writing direction of the element, setting it either to a left-to-right writing direction or a right-to-left writing direction. If the user does so, the user agent must then run the following steps:
Set the element's dir
attribute to "ltr
" if the user
selected a left-to-right writing direction, and "rtl
" if the user selected a
right-to-left writing direction.
Queue a task to fire a simple
event that bubbles named input
at the textarea
element.
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.
The Soft state
indicates that the text in the textarea
is not to be
wrapped when it is submitted (though it can still be wrapped in the
rendering).
The Hard state
indicates that the text in the textarea
is to have
newlines added by the user agent so that the text is wrapped when it
is submitted.
If the element's wrap
attribute is in the Hard state, the cols
attribute must be
specified.
For historical reasons, the element's value is normalised in
three different ways for three different purposes. The raw value is the value as
it was originally set. It is not normalized. The API value is the value
used in the value
IDL
attribute. It is normalized so that line breaks use "LF" (U+000A) characters. Finally, there is the form submission value. It is normalized so that line
breaks use U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) character
pairs, and in addition, if necessary given the element's wrap
attribute, additional line
breaks are inserted to wrap the text at the given width.
The element's API value is defined to be the element's raw value with the following transformation applied:
Replace every U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) character pair from the raw value with a single "LF" (U+000A) character.
Replace every remaining U+000D CARRIAGE RETURN character from the raw value with a single "LF" (U+000A) character.
The element's value is defined to be the element's raw value with the following transformation applied:
Replace every occurrence of a "CR" (U+000D) character not followed by a "LF" (U+000A) character, and every occurrence of a "LF" (U+000A) character not preceded by a "CR" (U+000D) 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-unit 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 short hint (a word or short phrase)
intended to aid the user with data entry when the control has no
value. 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 "LF" (U+000A) or "CR" (U+000D)
characters.
The placeholder
attribute should not be used as an alternative to a
label
. For a longer hint or other advisory text, the
title
attribute is more
appropriate.
These mechanisms are very similar but subtly
different: the hint given by the control's label
is
shown at all times; the short hint given in the placeholder
attribute is
shown before the user enters a value; and the hint in the title
attribute is shown when the user
requests further help.
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 dirname
attribute is a form control dirname
attribute.
The form
attribute is used to
explicitly associate the textarea
element with its
form owner. The name
attribute represents the element's name. The disabled
attribute is used to make
the control non-interactive and to prevent its value from being
submitted. The autofocus
attribute controls focus.
type
Returns the string "textarea
".
value
Returns the current value of the element.
Can be set, to change the value.
The cols
, placeholder
,
required
, rows
, and wrap
attributes must
reflect the respective content attributes of the same
name. The cols
and rows
attributes are limited
to only non-negative numbers greater than zero. The cols
attribute's default value is
20. The rows
attribute's
default value is 2. The dirName
IDL
attribute must reflect the dirname
content attribute. 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 API value; on setting, it
must set the element's raw
value to the new value, set the element's dirty value flag to true, and
should then move the text entry cursor position to the end of the
text field, unselecting any selected text and resetting the
selection direction to none.
The textLength
IDL
attribute must return the code-unit length of the
element's API
value.
The willValidate
, validity
, and validationMessage
IDL
attributes, and the checkValidity()
and setCustomValidity()
methods, are part of the constraint validation API. The
labels
IDL attribute provides a
list of the element's label
s. The select()
, selectionStart
,
selectionEnd
,
selectionDirection
,
setRangeText()
,
and setSelectionRange()
methods and IDL attributes expose the element's text selection. The
autofocus
, disabled
, form
, and name
IDL attributes are part of the
element's forms API.
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>
To specify a maximum length for the comments, one can use
the maxlength
attribute:
<p>If you have any short comments, please let us know: <textarea cols=80 name=comments maxlength=200></textarea></p>
To give a default value, text can be included inside the element:
<p>If you have any comments, please let us know: <textarea cols=80 name=comments>You rock!</textarea></p>
To have the browser submit the directionality of
the element along with the value, the dirname
attribute can be
specified:
<p>If you have any comments, please let us know (you may use either English or Hebrew for your comments): <textarea cols=80 name=comments dirname=comments.dir></textarea></p>
keygen
elementautofocus
challenge
disabled
form
keytype
name
interface HTMLKeygenElement : HTMLElement { attribute boolean autofocus; attribute DOMString challenge; attribute boolean disabled; readonly attribute HTMLFormElement? form; attribute DOMString keytype; attribute DOMString name; readonly attribute DOMString type; readonly attribute boolean willValidate; readonly attribute ValidityState validity; readonly attribute DOMString validationMessage; boolean checkValidity(); void setCustomValidity(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. [RFC4648] [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.
type
Returns the string "keygen
".
The challenge
IDL
attribute must reflect the content attribute of the
same name.
The keytype
IDL attribute must reflect the content attribute of the
same name, limited to only known values.
The type
IDL
attribute must return the value "keygen
".
The willValidate
, validity
, and validationMessage
IDL
attributes, and the checkValidity()
and setCustomValidity()
methods, are part of the constraint validation API. The
labels
IDL attribute provides a
list of the element's label
s. The autofocus
, disabled
, form
, and name
IDL attributes are part of the
element's forms API.
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 TLS 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
elementfor
form
name
interface 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(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 that are
case-sensitive, 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.
The element also has a default value. Initially, the default value must be the empty string.
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.
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 value mode flag
to default and then to
set the element's textContent
IDL attribute to the
value of the element's default value (thus
replacing the element's child nodes).
value
[ = value ]Returns the element's current value.
Can be set, to change the value.
defaultValue
[ = value ]Returns the element's current default value.
Can be set, to change the default value.
type
Returns the string "output
".
The value
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
IDL
attributes, and the checkValidity()
and setCustomValidity()
methods, are part of the constraint validation API. The
labels
IDL attribute provides a
list of the element's label
s. The form
and name
IDL attributes are part of the
element's forms API.
A simple calculator could use output
for its
display of calculated results:
<form onsubmit="return false" oninput="o.value = a.valueAsNumber + b.valueAsNumber"> <input name=a type=number step=any> + <input name=b type=number step=any> = <output name=o></output> </form>
progress
elementprogress
element descendants.value
max
interface HTMLProgressElement : HTMLElement { attribute double value; attribute double max; readonly attribute double position; 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.
To make a determinate progress bar, add a value
attribute with the current
progress (either a number from 0.0 to 1.0, or, if the max
attribute is specified, a
number from 0 to the value of the max
attribute). To make an
indeterminate progress bar, remove the value
attribute.
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.
position
For 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.
If the progress bar is an indeterminate progress bar, then the
value
IDL
attribute, on getting, must return 0. Otherwise, it must return the
current value. On
setting, the given value must be converted to the best
representation of the number as a floating-point number and
then the value
content
attribute must be set to that string.
Setting the value
IDL attribute to itself when
the corresponding content attribute is absent would change the
progress bar from an indeterminate progress bar to a determinate
progress bar with no progress.
The max
IDL
attribute must reflect the content attribute of the
same name, limited to numbers greater than zero. The
default value for max
is
1.0.
The labels
IDL attribute
provides a list of the element's label
s.
meter
elementmeter
element descendants.value
min
max
low
high
optimum
interface HTMLMeterElement : HTMLElement { attribute double value; attribute double min; attribute double max; attribute double low; attribute double high; attribute double optimum; 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, then the
candidate maximum value is that value. Otherwise, the candidate
maximum value is 1.0.
If the candidate maximum value is greater than or equal to the minimum value, then the maximum value is the candidate maximum value. Otherwise, the maximum value is 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 candidate actual value. Otherwise, the candidate actual
value is zero.
If the candidate actual value is less than the minimum value, then the actual value is the minimum value.
Otherwise, if the candidate actual value is greater than the maximum value, then the actual value is the maximum value.
Otherwise, the actual value is the candidate actual value.
If the low
attribute is
specified and a value could be parsed out of it, then the
candidate low boundary is that value. Otherwise, the candidate low
boundary is the same as the minimum value.
If the candidate low boundary is less than the minimum value, then the low boundary is the minimum value.
Otherwise, if the candidate low boundary is greater than the maximum value, then the low boundary is the maximum value.
Otherwise, the low boundary is the candidate low boundary.
If the high
attribute is
specified and a value could be parsed out of it, then the
candidate high boundary is that value. Otherwise, the candidate
high boundary is the same as the maximum value.
If the candidate high boundary is less than the low boundary, then the high boundary is the low boundary.
Otherwise, if the candidate high boundary is greater than the maximum value, then the high boundary is the maximum value.
Otherwise, the high boundary is the candidate high boundary.
If the optimum
attribute is specified and a value could be parsed out of it, then
the candidate optimum point is that value. Otherwise, the
candidate optimum point is the midpoint between the minimum value
and the maximum value.
If the candidate optimum point is less than the minimum value, then the optimum point is the minimum value.
Otherwise, if the candidate optimum point is greater than the maximum value, then the optimum point is the maximum value.
Otherwise, the optimum point is the candidate optimum point.
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 from the low boundary up to the high boundary must be treated as a suboptimal region, and the remaining region 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 from the high boundary down to the low boundary must be treated as a suboptimal region, and the remaining region 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 value
IDL
attribute, on getting, must return the actual value. On setting, the
given value must be converted to the best representation of
the number as a floating-point number and then the value
content attribute must be set
to that string.
The min
IDL
attribute, on getting, must return the minimum value. On setting, the
given value must be converted to the best representation of
the number as a floating-point number and then the min
content attribute must be set to
that string.
The max
IDL
attribute, on getting, must return the maximum value. On setting, the
given value must be converted to the best representation of
the number as a floating-point number and then the max
content attribute must be set to
that string.
The low
IDL
attribute, on getting, must return the low boundary. On setting, the given
value must be converted to the best representation of the
number as a floating-point number and then the low
content attribute must be set to
that string.
The high
IDL
attribute, on getting, must return the high boundary. On setting, the
given value must be converted to the best representation of
the number as a floating-point number and then the high
content attribute must be set to
that string.
The optimum
IDL
attribute, on getting, must return the optimum value. On setting, the
given value must be converted to the best representation of
the number as a floating-point number and then the optimum
content attribute must be
set to that string.
The labels
IDL attribute
provides a list of the element's label
s.
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.
This feature allows authors to work around the lack
of support for nested form
elements.
If a form-associated element has a form
attribute specified, then that
attribute's value must be the ID of a form
element in
the element's owner Document
.
The rules in this section are complicated by the
fact that although conforming documents will never contain nested
form
elements, it is quite possible (e.g. using a
script that performs DOM manipulation) to generate documents that
have such nested elements. They are also complicated by rules in the
HTML parser that, for historical reasons, can result in a
form-associated element being associated with a
form
element that is not its ancestor.
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 or one of its
ancestors is inserted into a Document
, then the
user agent must reset the form owner of that
form-associated element. The
HTML parser overrides this requirement when inserting
form controls.
When an element is removed from a Document
resulting in a
form-associated element and its form owner
(if any) no longer being in the same home subtree, then
the user agent must reset the form owner of that
form-associated element.
When a form-associated element's form
attribute is set, changed, or
removed, 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 elements in the
Document
changes, then the user agent must reset
the form owner of that form-associated
element.
When a form-associated element has a form
attribute and an element with an
ID is inserted into or removed from the
Document
, 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 and is itself in a
Document
, 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 happens as follows: First, the "e" node gets associated
with "c" in the HTML parser. Then, the innerHTML
algorithm moves the nodes
from the temporary document to the "b" element. At this point, the
nodes see their ancestor chain change, and thus all the "magic"
associations done by the parser are reset to normal ancestor
associations.
This example is a non-conforming document, though, as it is a
violation of the content models to nest form
elements.
form
Returns the element's form owner.
Returns null if there isn't one.
Form-associated
elements have a form
IDL attribute, which,
on getting, must return the element's form owner, or
null if there isn't one.
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.
Any non-empty value for name
is allowed, but the names "_charset_
" and "isindex
" are special:
isindex
This value, if used as the name of a Text control that is the first
control in a form that is submitted using the application/x-www-form-urlencoded
mechanism, causes the submission to only include the value of this
control, with no name.
_charset_
This value, if used as the name of a Hidden control with no value
attribute, is automatically
given a value during submission consisting of the submission
character encoding.
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.
To define the behaviour of constraint validation in the face of
the input
element's multiple
attribute,
input
elements can also have separately defined values.
The autofocus
content attribute allows the author to indicate that a control is to
be focused as soon as the page is loaded or as soon as the
dialog
within which it finds itself is shown, allowing
the user to just start typing without having to manually focus the
main control.
The autofocus
attribute is
a boolean attribute.
An element's nearest ancestor autofocus scoping root
element is the element itself if the element is a
dialog
element, or else is the element's nearest
ancestor dialog
element, if any, or else is the
element's root element.
There must not be two elements with the same nearest
ancestor autofocus scoping root element that both have the
autofocus
attribute
specified.
When an element with the autofocus
attribute specified is
inserted into a
document, user agents should run the following steps:
Let target be the element's
Document
.
If target has no browsing context, abort these steps.
If target's browsing context has no top-level browsing context (e.g. it is a nested browsing context with no parent browsing context), abort these steps.
If target's active sandboxing flag set has the sandboxed automatic features browsing context flag, abort these steps.
If target's origin is not
the same as the
origin of the Document
of the currently
focused element in target's top-level
browsing context, abort these steps.
If target's origin is not the same as the origin of the active document of target's top-level browsing context, abort these steps.
If the user agent has already reached the last step of this
list of steps in response to an element being inserted into a
Document
whose top-level browsing
context's active document is the same as target's top-level browsing context's
active document, abort these steps.
If the user has indicated (for example, by starting to type in a form control) that he does not wish focus to be changed, then optionally abort these steps.
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.
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, its dirty value flag is true, its value was last changed by a user edit (as opposed to a change made by a script), and the code-unit 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-unit 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 non-empty URL potentially surrounded by
spaces.
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.The invalid value default for these attributes is the GET state. (There is no missing value default.)
The method of an element is
one of those 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 invalid value default for these attributes is the
application/x-www-form-urlencoded
state. (There is no missing value default.)
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 the
Document
contains 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 required 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
IDL
attribute must reflect the content attribute of the
same name, except that on getting, when the content attribute is
missing or its value is the empty string, the document's
address must be returned instead. The target
IDL attribute must
reflect the content attribute of the same name. The
method
and enctype
IDL attributes
must reflect the respective content attributes of the
same name, limited to only known values. The encoding
IDL attribute
must reflect the enctype
content attribute,
limited to only known values. The noValidate
IDL
attribute must reflect the novalidate
content attribute. The
formAction
IDL
attribute must reflect the formaction
content attribute,
except that on getting, when the content attribute is missing or its
value is the empty string, the document's address must
be returned instead. The formEnctype
IDL
attribute must reflect the formenctype
content attribute,
limited to only known values. The formMethod
IDL
attribute must reflect the formmethod
content attribute,
limited to only known values. The formNoValidate
IDL
attribute must reflect the formnovalidate
content
attribute. The formTarget
IDL
attribute must reflect the formtarget
content attribute.
A form control dirname
attribute
on a form control element enables the submission of the
directionality of the element, and gives the name of the
field that contains this value during form submission.
If such an attribute is specified, its value must not be the empty
string.
The input
and textarea
elements define
the following members in their DOM interfaces for handling their
selection:
void select(); attribute unsigned long selectionStart; attribute unsigned long selectionEnd; attribute DOMString selectionDirection; void setSelectionRange(unsigned long start, unsigned long end, optional DOMString direction = "preserve");
These methods and attributes expose and control the selection of
input
and textarea
text fields.
select
()Selects everything in the text field.
selectionStart
[ = value ]Returns the offset to the start of the selection.
Can be set, to change the start of the selection.
selectionEnd
[ = value ]Returns the offset to the end of the selection.
Can be set, to change the end of the selection.
selectionDirection
[ = value ]Returns the current direction of the selection.
Can be set, to change the direction of the selection.
The possible values are "forward
", "backward
", and "none
".
setSelectionRange
(start, end [, direction] )Changes the selection to cover the given substring in the given direction. If the direction is omitted, it will be reset to be the platform default (none or forward).
For input
elements, calling these methods while they
don't apply, and getting or setting these attributes while they
don't apply, must throw an InvalidStateError
exception.
Otherwise, they must act as described below.
For input
elements, these methods and attributes
must operate on the element's value. For textarea
elements, these methods and attributes must operate on the element's
raw value.
Where possible, user interface features for changing the text
selection in input
and textarea
elements
must be implemented in terms of the DOM API described in this
section, so that, e.g., all the same events fire.
The selections of input
and textarea
elements have a direction, which is either forward,
backward, or none. This direction is set when the user
manipulates the selection. The exact meaning of the selection
direction depends on the platform.
On Windows, the direction indicates the position of the caret relative to the selection: a forward selection has the caret at the end of the selection and a backward selection has the caret at the start of the selection. Windows has no none direction. On Mac, the direction indicates which end of the selection is affected when the user adjusts the size of the selection using the arrow keys with the Shift modifier: the forward direction means the end of the selection is modified, and the backwards direction means the start of the selection is modified. The none direction is the default on Mac, it indicates that no particular direction has yet been selected. The user sets the direction implicitly when first adjusting the selection, based on which directional arrow key was used.
The select()
method
must cause the contents of the text field to be fully selected, with
the selection direction being none, if the platform support
selections with the direction none, or otherwise
forward. The user agent must then queue a task
to fire a simple event that bubbles named select
at the element, using the
user interaction task source as the task source.
The selectionStart
attribute must, on getting, return the offset (in logical order) to
the character that immediately follows the start of the
selection. If there is no selection, then it must return the offset
(in logical order) to the character that immediately follows the
text entry cursor.
On setting, it must act as if the setSelectionRange()
method had been called, with the new value as the first argument;
the current value of the selectionEnd
attribute as the second argument, unless the current value of the
selectionEnd
is
less than the new value, in which case the second argument must also
be the new value; and the current value of the selectionDirection
as the third argument.
The selectionEnd
attribute must, on getting, return the offset (in logical order) to
the character that immediately follows the end of the selection. If
there is no selection, then it must return the offset (in logical
order) to the character that immediately follows the text entry
cursor.
On setting, it must act as if the setSelectionRange()
method had been called, with the current value of the selectionStart
attribute as the first argument, the new value as the second
argument, and the current value of the selectionDirection
as the third argument.
The selectionDirection
attribute must, on getting, return the string corresponding to the
current selection direction: if the direction is forward,
"forward
"; if the direction is
backward, "backward
"; and otherwise,
"none
".
On setting, it must act as if the setSelectionRange()
method had been called, with the current value of the selectionStart
attribute as the first argument, the current value of the selectionEnd
attribute as the second argument, and the new value as the third
argument.
The setSelectionRange(start, end, direction)
method must set the selection
of the text field to the sequence of characters starting with the
character at the startth position (in logical
order) and ending with the character at the (end-1)th position. Arguments greater than the
length of the value of the text field must be treated as pointing at
the end of the text field. If end is less than
or equal to start then the start of the
selection and the end of the selection must both be placed
immediately before the character with offset end. In UAs where there is no concept of an empty
selection, this must set the cursor to be just before the character
with offset end. The direction of the selection
must be set to backward if direction is a
case-sensitive match for the string "backward
", forward if direction is a case-sensitive match for
the string "forward
" or if the platform does
not support selections with the direction none, and
none otherwise (including if the argument is omitted). The
user agent must then queue a task to fire a
simple event that bubbles named select
at the element, using the
user interaction task source as the task source.
All elements to which this API applies have either a selection or a text entry cursor position at all times (even for elements that are not being rendered). User agents should follow platform conventions to determine their initial state.
Characters with no visible rendering, such as U+200D ZERO WIDTH JOINER, still count as characters. Thus, for instance, the selection can include just an invisible character, and the text insertion cursor can be placed to one side or another of such a character.
To obtain the currently selected text, the following JavaScript suffices:
var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);
To add some text at the start of a text control, while maintaining the text selection, the three attributes must be preserved:
var oldStart = control.selectionStart; var oldEnd = control.selectionEnd; var oldDirection = control.selectionDirection; var prefix = "http://"; control.value = prefix + control.value; control.setSelectionRange(oldStart + prefix.length, oldEnd + prefix.length, oldDirection);
A submittable 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 object
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
, select
required
,
textarea
required
), or, in the case of
an element in a radio button group, any of the other
elements in the group has a required
attribute.
When a control that allows arbitrary user input has a value that is not in the correct syntax (E-mail, URL).
When a control has a value that doesn't satisfy the
pattern
attribute.
When a control has a value that is too long for the
form control maxlength
attribute (input
maxlength
,
textarea
maxlength
).
When a control has a value that is too low for the min
attribute.
When a control has a value that is too high for the
max
attribute.
When a control has a value that doesn't fit the rules
given by the step
attribute.
When a control's custom validity error
message (as set by the element's setCustomValidity()
method) is not the empty string.
An element can still suffer from these states even when the element is disabled; thus these states can be represented in the DOM even if validating the form during submission wouldn't indicate a problem to the user.
An element satisfies its constraints if it is not suffering from any of the above validity states.
When the user agent is required to statically validate the
constraints of form
element form, it must run the following steps, which return
either a positive result (all the controls in the form are
valid) or a negative result (there are invalid controls)
along with a (possibly empty) list of elements that are invalid and
for which no script has claimed responsibility:
Let controls be a list of all the submittable elements whose form owner is form, in tree order.
Let invalid controls be an initially empty list of elements.
For each element field in controls, in tree order, run the following substeps:
If field is not a candidate for constraint validation, then move on to the next element.
Otherwise, if field satisfies its constraints, then move on to the next element.
Otherwise, add field to invalid controls.
If invalid controls is empty, then return a positive result and abort these steps.
Let unhandled invalid controls be an initially empty list of elements.
For each element field in invalid controls, if any, in tree order, run the following substeps:
Fire a simple event named invalid
that is cancelable at field.
If the event was not canceled, then add field to unhandled invalid controls.
Return a negative result with the list of elements in the unhandled invalid controls list.
If a user agent is to interactively validate the
constraints of form
element form, then the user agent must run the following
steps:
Statically validate the constraints of form, and let unhandled invalid controls be the list of elements returned if the result was negative.
If the result was positive, then return that result and abort these steps.
Report the problems with the constraints of at least one of
the elements given in unhandled invalid
controls to the user. User agents may focus one of those
elements in the process, by running the focusing steps
for that element, and may change the scrolling position of the
document, or perform some other action that brings the element to
the user's attention. User agents may report more than one
constraint violation. User agents may coalesce related constraint
violation reports if appropriate (e.g. if multiple radio buttons in
a group are marked as
required, only one error need be reported). If one of the controls
is not being rendered (e.g. it has the hidden
attribute set) then user agents
may report a script error.
Return a negative result.
willValidate
Returns true if the element will be validated when the form is submitted; false otherwise.
setCustomValidity
(message)Sets a custom error, so that the element would fail to validate. The given message is the message to be shown to the user when reporting the problem to the user.
If the argument is the empty string, clears the custom error.
validity
. valueMissing
Returns true if the element has no value but is a required field; false otherwise.
validity
. typeMismatch
Returns true if the element's value is not in the correct syntax; false otherwise.
validity
. patternMismatch
Returns true if the element's value doesn't match the provided pattern; false otherwise.
validity
. tooLong
Returns true if the element's value is longer than the provided maximum length; false otherwise.
validity
. rangeUnderflow
Returns true if the element's value is lower than the provided minimum; false otherwise.
validity
. rangeOverflow
Returns true if the element's value is higher than the provided maximum; false otherwise.
validity
. stepMismatch
Returns true if the element's value doesn't fit the rules given by the step
attribute; false otherwise.
validity
. customError
Returns true if the element has a custom error; false otherwise.
validity
. valid
Returns true if the element's value has no validity problems; false otherwise.
checkValidity
()Returns true if the element's value has no validity problems;
false otherwise. Fires an invalid
event at the element in the
latter case.
validationMessage
Returns the error message that would be shown to the user if the element was to be checked for validity.
The willValidate
attribute must return true if an element is a candidate for
constraint validation, and false otherwise (i.e. false if any
conditions are barring it from constraint validation).
The setCustomValidity(message)
, when invoked, must set the
custom validity error message to the value of the given
message argument.
In the following example, a script checks the value of a form
control each time it is edited, and whenever it is not a valid
value, uses the setCustomValidity()
method
to set an appropriate message.
<label>Feeling: <input name=f type="text" oninput="check(this)"></label> <script> function check(input) { if (input.value == "good" || input.value == "fine" || input.value == "tired") { input.setCustomValidity('"' + input.value + '" is not a feeling.'); } else { // input is fine -- reset the error message input.setCustomValidity(''); } } </script>
The validity
attribute must return a ValidityState
object that
represents the validity states of the element. This
object is live, and the same object must be returned
each time the element's validity
attribute is retrieved.
interface ValidityState { readonly attribute boolean valueMissing; readonly attribute boolean typeMismatch; readonly attribute boolean patternMismatch; readonly attribute boolean tooLong; readonly attribute boolean rangeUnderflow; readonly attribute boolean rangeOverflow; readonly attribute boolean stepMismatch; readonly attribute boolean customError; readonly attribute boolean valid; };
A ValidityState
object has the following
attributes. On getting, they must return true if the corresponding
condition given in the following list is true, and false
otherwise.
valueMissing
The control is suffering from being missing.
typeMismatch
The control is suffering from a type mismatch.
patternMismatch
The control is suffering from a pattern mismatch.
tooLong
The control is suffering from being too long.
rangeUnderflow
The control is suffering from an underflow.
rangeOverflow
The control is suffering from an overflow.
stepMismatch
The control is suffering from a step mismatch.
customError
The control is suffering from a custom error.
valid
None of the other conditions are true.
When the checkValidity()
method is invoked, if the element is a candidate for
constraint validation and does not satisfy its constraints, the user
agent must fire a simple event named invalid
that is cancelable (but in this
case has no default action) at the element and return
false. Otherwise, it must only return true without doing anything
else.
The validationMessage
attribute must return the empty string if the element is not a
candidate for constraint validation or if it is one but
it satisfies its constraints;
otherwise, it must return a suitably localized message that the user
agent would show the user if this were the only form control with a
validity constraint problem. If the user agent would not actually
show a textual message in such a situation (e.g. it would show a
graphical cue instead), then the attribute must return a suitably
localized message that expresses (one or more of) the validity
constraint(s) that the control does not satisfy. If the element is a
candidate for constraint validation and is
suffering from a custom error, then the custom
validity error message should be present in the return
value.
Servers should not rely on client-side validation. Client-side validation can be intentionally bypassed by hostile users, and unintentionally bypassed by users of older user agents or automated tools that do not implement these features. The constraint validation features are only intended to improve the user experience, not to provide any kind of security mechanism.
This section is non-normative.
When a form is submitted, the data in the form is converted into the structure specified by the enctype, and then sent to the destination specified by the action using the given method.
For example, take the following form:
<form action="/find.cgi" method=get> <input type=text name=t> <input type=search name=q> <input type=submit> </form>
If the user types in "cats" in the first field and "fur" in the
second, and then hits the submit button, then the user agent will
load /find.cgi?t=cats&q=fur
.
On the other hand, consider this form:
<form action="/find.cgi" method=post enctype="multipart/form-data"> <input type=text name=t> <input type=search name=q> <input type=submit> </form>
Given the same user input, the result on submission is quite different: the user agent instead does an HTTP POST to the given URL, with as the entity body something like the following text:
------kYFrd4jNJEgCervE Content-Disposition: form-data; name="t" cats ------kYFrd4jNJEgCervE Content-Disposition: form-data; name="q" fur ------kYFrd4jNJEgCervE--
A form
element's default button is the
first submit button in
tree order whose form owner is that
form
element.
If the user agent supports letting the user submit a form implicitly (for example, on some platforms hitting the "enter" key while a text field is focused implicitly submits the form), then doing so for a form whose default button has a defined activation behavior must cause the user agent to run synthetic click activation steps on that default button.
Consequently, if the default button is disabled, the form is not submitted when such an implicit submission mechanism is used. (A button has no activation behavior when disabled.)
There are pages on the Web that are only usable if there is a way to implicitly submit forms, so user agents are strongly encouraged to support this.
If the form has no submit button, then the
implicit submission mechanism must do nothing if the form has more
than one field that blocks implicit submission, and must
submit the
form
element from the form
element itself
otherwise.
For the purpose of the previous paragraph, an element is a
field that blocks implicit submission of a form
element if it is an input
element whose form
owner is that form
element and whose type
attribute is in one of the
following states:
Text,
Search,
URL,
Telephone,
E-mail,
Password,
Date and Time,
Date,
Month,
Week,
Time,
Local Date and Time,
Number
When a form
element form is submitted from an element submitter (typically a button), optionally with a
submitted from submit()
method flag set, the
user agent must run the following steps:
Let form document be the form's Document
.
If form document has no associated browsing context or its active sandboxing flag set has its sandboxed forms browsing context flag set, then abort these steps without doing anything.
Let form browsing context be the browsing context of form document.
If form is already being submitted
(i.e. the form was submitted again while processing
the events fired from the next two steps, probably from a script
redundantly calling the submit()
method on form), then abort these steps. This doesn't affect
the earlier instance of this algorithm.
If the submitted from submit()
method flag is not
set, and the submitter element's no-validate state is false,
then interactively validate the constraints of form and examine the result: if the result is
negative (the constraint validation concluded that there were
invalid fields and probably informed the user of this) then abort
these steps.
If the submitted from submit()
method flag is not
set, then fire a simple event that is cancelable named
submit
, at form. If the event's default action is prevented
(i.e. if the event is canceled) then abort these steps. Otherwise,
continue (effectively the default action is to perform the
submission).
Let form data set be the result of constructing the form data set for form in the context of submitter.
Let action be the submitter element's action.
If action is the empty string, let action be the document's address of the form document.
This step is a willful violation of RFC 3986, which would require base URL processing here. This violation is motivated by a desire for compatibility with legacy content. [RFC3986]
Resolve the URL action, relative to the submitter element. If this fails, abort these steps. Otherwise, let action be the resulting absolute URL.
Let scheme be the <scheme> of the resulting absolute URL.
Let enctype be the submitter element's enctype.
Let method be the submitter element's method.
Let target be the submitter element's target.
If the user indicated a specific browsing context to use when submitting the form, then let target browsing context be that browsing context. Otherwise, apply the rules for choosing a browsing context given a browsing context name using target as the name and form browsing context as the context in which the algorithm is executed, and let target browsing context be the resulting browsing context.
If target browsing context was created in the previous step, or if the form document has not yet completely loaded, then let replace be true. Otherwise, let it be false.
Otherwise, select the appropriate row in the table below based on the value of scheme as given by the first cell of each row. Then, select the appropriate cell on that row based on the value of method as given in the first cell of each column. Then, jump to the steps named in that cell and defined below the table.
GET | POST | |
---|---|---|
http
| Mutate action URL | Submit as entity body |
https
| Mutate action URL | Submit as entity body |
ftp
| Get action URL | Get action URL |
javascript
| Get action URL | Get action URL |
data
| Get action URL | Post to data: |
mailto
| Mail with headers | Mail as body |
If scheme is not one of those listed in this table, then the behavior is not defined by this specification. User agents should, in the absence of another specification defining this, act in a manner analogous to that defined in this specification for similar schemes.
The behaviors are as follows:
Let query be the result of encoding the
form data set using the application/x-www-form-urlencoded
encoding
algorithm, interpreted as a US-ASCII string.
Let destination be a new URL that is equal to the action except that its <query> component is replaced by query (adding a "?" (U+003F) character if appropriate).
Navigate target browsing context to destination. If replace is true, then target browsing context must be navigated with replacement enabled.
Let entity body be the result of encoding the form data set using the appropriate form encoding algorithm.
Let MIME type be determined as follows:
application/x-www-form-urlencoded
application/x-www-form-urlencoded
".multipart/form-data
multipart/form-data;
", a
U+0020 SPACE character, the string "boundary=
", and the multipart/form-data
boundary string
generated by the multipart/form-data
encoding
algorithm.text/plain
text/plain
".Otherwise, navigate target browsing context to action using the HTTP method given by method and with entity body as the entity body, of type MIME type. If replace is true, then target browsing context must be navigated with replacement enabled.
Navigate target browsing context to action. If replace is true, then target browsing context must be navigated with replacement enabled.
Let data be the result of encoding the form data set using the appropriate form encoding algorithm.
If action contains the string "%%%%
" (four U+0025 PERCENT SIGN characters),
then %-escape all bytes in data that, if
interpreted as US-ASCII, do not match the unreserved
production in the URI Generic Syntax,
and then, treating the result as a US-ASCII string, further
%-escape all the U+0025 PERCENT SIGN characters in the resulting
string and replace the first occurrence of "%%%%
" in action with the
resulting double-escaped string. [RFC3986]
Otherwise, if action contains the string
"%%
" (two U+0025 PERCENT SIGN characters
in a row, but not four), then %-escape all characters in data that, if interpreted as US-ASCII, do not
match the unreserved
production in the URI
Generic Syntax, and then, treating the result as a US-ASCII
string, replace the first occurrence of "%%
" in action with the
resulting escaped string. [RFC3986]
Navigate target
browsing context to the potentially modified action (which will be a data:
URL). If replace is true, then target
browsing context must be navigated with replacement
enabled.
Let headers be the resulting encoding the
form data set using the application/x-www-form-urlencoded
encoding
algorithm, interpreted as a US-ASCII string.
Replace occurrences of "+" (U+002B) characters in
headers with the string "%20
".
Let destination consist of all the characters from the first character in action to the character immediately before the first "?" (U+003F) character, if any, or the end of the string if there are none.
Append a single "?" (U+003F) character to destination.
Append headers to destination.
Navigate target browsing context to destination. If replace is true, then target browsing context must be navigated with replacement enabled.
Let body be the resulting encoding the
form data set using the appropriate
form encoding algorithm and then %-escaping all the bytes
in the resulting byte string that, when interpreted as US-ASCII,
do not match the unreserved
production in
the URI Generic Syntax. [RFC3986]
Let destination have the same value as action.
If destination does not contain a "?" (U+003F) character, append a single "?" (U+003F) character to destination. Otherwise, append a single U+0026 AMPERSAND character (&).
Append the string "body=
" to destination.
Append body, interpreted as a US-ASCII string, to destination.
Navigate target browsing context to destination. If replace is true, then target browsing context must be navigated with replacement enabled.
The appropriate form encoding algorithm is determined as follows:
application/x-www-form-urlencoded
application/x-www-form-urlencoded
encoding
algorithm.multipart/form-data
multipart/form-data
encoding
algorithm.text/plain
text/plain
encoding
algorithm.The algorithm to construct the form data set for a form form optionally in the context of a submitter submitter is as follows. If not specified otherwise, submitter is null.
Let controls be a list of all the submittable elements whose form owner is form, in tree order.
Let the form data set be a list of name-value-type tuples, initially empty.
Loop: For each element field in controls, in tree order, run the following substeps:
If any of the following conditions are met, then skip these substeps for this element:
datalist
element ancestor.input
element whose type
attribute is in the Checkbox state and
whose checkedness is
false.input
element whose type
attribute is in the Radio Button state and
whose checkedness is
false.input
element whose type
attribute is in the Image Button state, and
either the field element does not have a
name
attribute specified, or
its name
attribute's value is
the empty string.object
element that is not using a
plugin.Otherwise, process field as follows:
Let type be the value of the type
IDL attribute of field.
If the field element is an
input
element whose type
attribute is in the Image Button state,
then run these further nested substeps:
If the field element has a name
attribute specified and its
value is not the empty string, let name be
that value followed by a single "." (U+002E) character.
Otherwise, let name be the empty
string.
Let namex be the string consisting of the concatenation of name and a single "x" (U+0078) character.
Let namey be the string consisting of the concatenation of name and a single "y" (U+0079) character.
The field element is submitter, and before this algorithm was invoked the user indicated a coordinate. Let x be the x-component of the coordinate selected by the user, and let y be the y-component of the coordinate selected by the user.
Append an entry to the form data set with the name namex, the value x, and the type type.
Append an entry to the form data set with the name namey and the value y, and the type type.
Skip the remaining substeps for this element: if there are any more elements in controls, return to the top of the loop step, otherwise, jump to the end step below.
Let name be the value of the field element's name
attribute.
If the field element is a
select
element, then for each option
element in the select
element whose selectedness is true,
append an entry to the form data set with the
name as the name, the value of the
option
element as the value, and type as the type.
Otherwise, if the field element is an
input
element whose type
attribute is in the Checkbox state or the
Radio Button state,
then run these further nested substeps:
If the field element has a value
attribute specified, then
let value be the value of that attribute;
otherwise, let value be the string
"on
".
Append an entry to the form data set with name as the name, value as the value, and type as the type.
Otherwise, if the field element is an
input
element whose type
attribute is in the File Upload state, then for
each file selected in the
input
element, append an entry to the form data set with the name as
the name, the file (consisting of the name, the type, and the
body) as the value, and type as the type. If
there are no selected files,
then append an entry to the form data set
with the name as the name, the empty string
as the value, and application/octet-stream
as the
type.
Otherwise, if the field element is an
object
element: try to obtain a form submission
value from the plugin,
and if that is successful, append an entry to the form data set with name as the
name, the returned form submission value as the value, and the
string "object
" as the type.
Otherwise, append an entry to the form data set with name as the name, the value of the field element as the value, and type as the type.
If the element has a form control dirname
attribute, and that attribute's
value is not the empty string, then run these substeps:
Let dirname be the value of the
element's dirname
attribute.
Let dir be the string "ltr
" if the directionality of the
element is 'ltr', and "rtl
" otherwise (i.e. when the
directionality of the element is 'rtl').
Append an entry to the form data set
with dirname as the name, dir as the value, and the string "direction
" as the type.
An element can only have a form control
dirname
attribute if it is a
textarea
element or an input
element
whose type
attribute is in
either the Text state
or the Search
state.
End: For the name of each entry in the form data set, and for the value of each entry in
the form data set whose type is not "file
" or "textarea
", replace
every occurrence of a "CR" (U+000D) character not
followed by a "LF" (U+000A) character, and every
occurrence of a "LF" (U+000A) character not preceded by a
"CR" (U+000D) character, by a two-character string
consisting of a U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF)
character pair.
In the case of the value of textarea
elements, this newline normalization is already performed during
the conversion of the control's raw value into the
control's value (which also
performs any necessary line wrapping). In the case of
input
elements type
attributes in the File Upload state, the value
is not normalized.
Return the form data set.
This form data set encoding is in many ways an aberrant monstrosity, the result of many years of implementation accidents and compromises leading to a set of requirements necessary for interoperability, but in no way representing good design practices. In particular, readers are cautioned to pay close attention to the twisted details involving repeated (and in some cases nested) conversions between character encodings and byte sequences.
The application/x-www-form-urlencoded
encoding
algorithm is as follows:
Let result be the empty string.
If the form
element has an accept-charset
attribute,
then, taking into account the characters found in the form data set's names and values, and the character
encodings supported by the user agent, select a character encoding
from the list given in the form
's accept-charset
attribute
that is an ASCII-compatible character encoding. If
none of the encodings are supported, or if none are listed, then
let the selected character encoding be UTF-8.
Otherwise, if the document's character encoding is an ASCII-compatible character encoding, then that is the selected character encoding.
Otherwise, let the selected character encoding be UTF-8.
Let charset be the preferred MIME name of the selected character encoding.
For each entry in the form data set, perform these substeps:
If the entry's name is "_charset_
"
and its type is "hidden
", replace its value
with charset.
If the entry's type is "file
",
replace its value with the file's filename only.
For each character in the entry's name and value that cannot be expressed using the selected character encoding, replace the character by a string consisting of a U+0026 AMPERSAND character (&), a "#" (U+0023) character, one or more characters in the range ASCII digits representing the Unicode code point of the character in base ten, and finally a U+003B SEMICOLON character (;).
Encode the entry's name and value using the selected character encoding. The entry's name and value are now byte strings.
For each byte in the entry's name and value, apply the appropriate subsubsteps from the following list:
Leave the byte as is.
Let s be a string consisting of a "%" (U+0025) character followed by two characters in the ranges ASCII digits and U+0041 LATIN CAPITAL LETTER A to U+0046 LATIN CAPITAL LETTER F representing the hexadecimal value of the byte in question (zero-padded if necessary).
Encode the string s as US-ASCII, so that it is now a byte string.
Replace the byte in question in the name or value being processed by the bytes in s, preserving their relative order.
Interpret the entry's name and value as Unicode strings encoded in US-ASCII. (All of the bytes in the string will be in the range 0x00 to 0x7F; the high bit will be zero throughout.) The entry's name and value are now Unicode strings again.
If the entry's name is "isindex
", its type is "text
", and this is the first entry in the form data set, then append the value to result and skip the rest of the substeps for this
entry, moving on to the next entry, if any, or the next step in
the overall algorithm otherwise.
If this is not the first entry, append a single U+0026 AMPERSAND character (&) to result.
Append the entry's name to result.
Append a single "=" (U+003D) character to result.
Append the entry's value to result.
Encode result as US-ASCII and return the resulting byte stream.
To decode application/x-www-form-urlencoded
payloads, the following algorithm should be used. This
algorithm uses as inputs the payload itself, payload, consisting of a Unicode string using only
characters in the range U+0000 to U+007F; a default character
encoding encoding; and optionally an isindex flag indicating that the payload is to be
processed as if it had been generated for a form containing an isindex
control. The output of
this algorithm is a sorted list of name-value pairs. If the isindex flag is set and the first control really was
an isindex
control, then
the first name-value pair will have as its name the empty
string.
Let strings be the result of strictly splitting the string payload on U+0026 AMPERSAND characters (&).
If the isindex flag is set and the first string in strings does not contain a "=" (U+003D) character, insert a U+003D EQUALS SIGN character (=) at the start of the first string in strings.
Let pairs be an empty list of name-value pairs.
For each string string in strings, run these substeps:
If string contains a "=" (U+003D) character, then let name be the substring of string from the start of string up to but excluding its first "=" (U+003D) character, and let value be the substring from the first character, if any, after the first "=" (U+003D) character up to the end of string. If the first U+003D EQUALS SIGN character (=) is the first character, then name will be the empty string. If it is the last character, then value will be the empty string.
Otherwise, string contains no "=" (U+003D) characters. Let name have the value of string and let value be the empty string.
Replace any "+" (U+002B) characters in name and value with U+0020 SPACE characters.
Replace any escape in name and value with the character represented by the escape. This replacement most not be recursive.
An escape is a "%" (U+0025) character followed by two characters in the ranges ASCII digits, U+0041 LATIN CAPITAL LETTER A to U+0046 LATIN CAPITAL LETTER F, and U+0061 LATIN SMALL LETTER A to U+0066 LATIN SMALL LETTER F.
The character represented by an escape is the Unicode character whose code point is equal to the value of the two characters after the "%" (U+0025) character, interpreted as a hexadecimal number (in the range 0..255).
So for instance the string "A%2BC
" would become "A+C
".
Similarly, the string "100%25AA%21
"
becomes the string "100%AA!
".
Convert the name and value strings to their byte representation in ISO-8859-1 (i.e. convert the Unicode string to a byte string, mapping code points to byte values directly).
Add a pair consisting of name and value to pairs.
If any of the name-value pairs in pairs
have a name component consisting of the string "_charset_
" encoded in US-ASCII, and the value
component of the first such pair, when decoded as US-ASCII, is the
name of a supported character encoding, then let encoding be that character encoding (replacing the
default passed to the algorithm).
Convert the name and value components of each name-value pair in pairs to Unicode by interpreting the bytes according to the encoding encoding.
Return pairs.
Parameters on the
application/x-www-form-urlencoded
MIME type are
ignored. In particular, this MIME type does not support the charset
parameter.
The multipart/form-data
encoding
algorithm is as follows:
Let result be the empty string.
If the algorithm was invoked with an explicit character
encoding, let the selected character encoding be that encoding.
(This algorithm is used by other specifications, which provide an
explicit character encoding to avoid the dependency on the
form
element described in the next paragraph.)
Otherwise, if the form
element has an accept-charset
attribute,
then, taking into account the characters found in the form data set's names and values, and the character
encodings supported by the user agent, select a character encoding
from the list given in the form
's accept-charset
attribute
that is an ASCII-compatible character encoding. If
none of the encodings are supported, or if none are listed, then
let the selected character encoding be UTF-8.
Otherwise, if the document's character encoding is an ASCII-compatible character encoding, then that is the selected character encoding.
Otherwise, let the selected character encoding be UTF-8.
Let charset be the preferred MIME name of the selected character encoding.
For each entry in the form data set, perform these substeps:
If the entry's name is "_charset_
" and its type is
"hidden
", replace its value with charset.
For each character in the entry's name and value that cannot be expressed using the selected character encoding, replace the character by a string consisting of a U+0026 AMPERSAND character (&), a "#" (U+0023) character, one or more characters in the range ASCII digits representing the Unicode code point of the character in base ten, and finally a U+003B SEMICOLON character (;).
Encode the (now mutated) form data set
using the rules described by RFC 2388, Returning Values from
Forms: multipart/form-data
, and
return the resulting byte stream. [RFC2388]
Each entry in the form data set is a field, the name of the entry is the field name and the value of the entry is the field value.
The order of parts must be the same as the order of fields in the form data set. Multiple entries with the same name must be treated as distinct fields.
In particular, this means that multiple files
submitted as part of a single <input type=file multiple>
element
will result in each file having its own field; the "sets of files"
feature ("multipart/mixed
") of RFC 2388 is
not used.
The parts of the generated multipart/form-data
resource that correspond to
non-file fields must not have a Content-Type
header
specified. Their names and values must be encoded using the
character encoding selected above (field names in particular do
not get converted to a 7-bit safe encoding as suggested in RFC
2388).
File names included in the generated multipart/form-data
resource (as part of file
fields) must use the character encoding selected above, though the
precise name may be approximated if necessary (e.g. newlines could
be removed from file names, quotes could be changed to "%22", and
characters not expressible in the selected character encoding
could be replaced by other characters). User agents must not use
the RFC 2231 encoding suggested by RFC 2388.
The boundary used by the user agent in generating the return
value of this algorithm is the multipart/form-data
boundary string. (This
value is used to generate the MIME type of the form submission
payload generated by this algorithm.)
For details on how to interpret multipart/form-data
payloads, see RFC 2388. [RFC2388]
The text/plain
encoding
algorithm is as follows:
Let result be the empty string.
If the form
element has an accept-charset
attribute,
then, taking into account the characters found in the form data set's names and values, and the character
encodings supported by the user agent, select a character encoding
from the list given in the form
's accept-charset
attribute.
If none of the encodings are supported, or if none are listed,
then let the selected character encoding be UTF-8.
Otherwise, the selected character encoding is the document's character encoding.
Let charset be the preferred MIME name of the selected character encoding.
If the entry's name is "_charset_
" and its type is
"hidden
", replace its value with charset.
If the entry's type is "file
", replace
its value with the file's filename only.
For each entry in the form data set, perform these substeps:
Append the entry's name to result.
Append a single "=" (U+003D) character to result.
Append the entry's value to result.
Append a "CR" (U+000D) "LF" (U+000A) character pair to result.
Encode result using the selected character encoding and return the resulting byte stream.
Payloads using the text/plain
format are intended to
be human readable. They are not reliably interpretable by computer,
as the format is ambiguous (for example, there is no way to
distinguish a literal newline in a value from the newline at the end
of the value).
When a form
element form is reset, the user agent must
fire a simple event named reset
, that is cancelable, at form, and then, if that event is not canceled, must
invoke the reset
algorithm of each resettable
element whose form owner is form.
Each resettable element
defines its own reset
algorithm. Changes made to form controls as part of these
algorithms do not count as changes caused by the user (and thus,
e.g., do not cause input
events to
fire).