input
element attributes
autocomplete
attributedirname
attributelist
attributereadonly
attributesize
attributerequired
attributemultiple
attributemaxlength
attributepattern
attributemin
and max
attributesstep
attributeplaceholder
attributeinput
element APIsinput
element attributesThese attributes only apply to an input
element if
its type
attribute is in a
state whose definition declares that the attribute applies. When an
attribute doesn't apply to an input
element, user
agents must ignore the attribute, regardless of the
requirements and definitions below.
autocomplete
attributeUser agents sometimes have features for helping users fill forms in, for example prefilling the user's address based on earlier user input.
The autocomplete
attribute is an enumerated attribute. The attribute has
three states. The on
keyword maps to the on state, and the
off
keyword maps to
the off
state. The attribute may also be omitted. The missing value
default is the default
state.
The off state indicates either that the control's input data is particularly sensitive (for example the activation code for a nuclear weapon); or that it is a value that will never be reused (for example a one-time-key for a bank login) and the user will therefore have to explicitly enter the data each time, instead of being able to rely on the UA to prefill the value for him; or that the document provides its own autocomplete mechanism and does not want the user agent to provide autocompletion values.
Conversely, the on state indicates that the value is not particularly sensitive and the user can expect to be able to rely on his user agent to remember values he has entered for that control.
The default state
indicates that the user agent is to use the autocomplete
attribute on the
element's form owner instead. (By default, the autocomplete
attribute of
form
elements is in the on state.)
Each input
element has a resulting
autocompletion state, which is either on or off.
When an input
element is in one of the following
conditions, the input
element's resulting
autocompletion state is on; otherwise, the
input
element's resulting autocompletion
state is off:
autocomplete
attribute is in the on state.autocomplete
attribute is in the default state,
and the element has no form owner.autocomplete
attribute is in the default state,
and the element's form owner's autocomplete
attribute is in
the on
state.When an input
element's resulting
autocompletion state is on, the user agent
may store the value entered by the user so that if the user returns
to the page, the UA can prefill the form. Otherwise, the user agent
should not remember the control's value, and should not offer past
values to the user.
In addition, if the resulting autocompletion state is off, values are reset when traversing the history.
The autocompletion mechanism must be implemented by the user agent acting as if the user had modified the element's value, and must be done at a time where the element is mutable (e.g. just after the element has been inserted into the document, or when the user agent stops parsing).
Banks frequently do not want UAs to prefill login information:
<p><label>Account: <input type="text" name="ac" autocomplete="off"></label></p> <p><label>PIN: <input type="password" name="pin" autocomplete="off"></label></p>
A user agent may allow the user to override the resulting autocompletion state and set it to always on, always allowing values to be remembered and prefilled), or always off, never remembering values. However, the ability to override the resulting autocompletion state to on should not be trivially accessible, as there are significant security implications for the user if all values are always remembered, regardless of the site's preferences.
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
should be placed inside the value
attribute instead of
inline.
<p> <label> Enter a breed: <input type="text" name="breed" list="breeds"> <datalist id="breeds"> <option value="Abyssinian"> <option value="Alpaca"> <!-- ... --> </datalist> </label> </p>
However, if the values need to be shown in legacy UAs, then
fallback content can be placed inside the datalist
element, as follows:
<p> <label> Enter a breed: <input type="text" name="breed" list="breeds"> </label> <datalist id="breeds"> <label> or select one from the list: <select name="breed"> <option value=""> (none selected) <option>Abyssinian <option>Alpaca <!-- ... --> </select> </label> </datalist> </p>
The fallback content will only be shown in UAs that don't
support datalist
. The options, on the other hand, will
be detected by all UAs, even though they are not direct children of
the datalist
element.
Note that if an option
element used in a
datalist
is selected
, it will be selected
by default by legacy UAs (because it affects the
select
), but it will not have any effect on the
input
element in UAs that support
datalist
.
readonly
attributeThe readonly
attribute is a boolean attribute that controls whether
or not the 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.
In the following example, the existing product identifiers cannot be modified, but they are still displayed as part of the form, for consistency with the row representing a new product (where the identifier is not yet filled in).
<form action="products.cgi" method=post enctype="multipart/form-data"> <table> <tr> <th> Product ID <th> Product name <th> Price <th> Action <tr> <td> <input readonly name="1.pid" value="H412"> <td> <input required name="1.pname" value="Floor lamp Ulke"> <td> $<input required type=number min=0 step=0.01 name="1.pprice" value="49.99"> <td> <button formnovalidate name="action" value="delete:1">Delete</button> <tr> <td> <input readonly name="2.pid" value="FG28"> <td> <input required name="2.pname" value="Table lamp Ulke"> <td> $<input required type=number min=0 step=0.01 name="2.pprice" value="24.99"> <td> <button formnovalidate name="action" value="delete:2">Delete</button> <tr> <td> <input required name="3.pid" value="" pattern="[A-Z0-9]+"> <td> <input required name="3.pname" value=""> <td> $<input required type=number min=0 step=0.01 name="3.pprice" value=""> <td> <button formnovalidate name="action" value="delete:3">Delete</button> </table> <p> <button formnovalidate name="action" value="add">Add</button> </p> <p> <button name="action" value="update">Save</button> </p> </form>
size
attributeThe size
attribute gives the number of characters that, in a visual
rendering, the user agent is to allow the user to see while editing
the element's value.
The size
attribute, if
specified, must have a value that is a valid non-negative
integer greater than zero.
If the attribute is present, then its value must be parsed using the rules for parsing non-negative integers, and if the result is a number greater than zero, then the user agent should ensure that at least that many characters are visible.
The size
IDL attribute is
limited to only non-negative numbers greater than
zero 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 considerd valid if the user types the same password in the password field and this third field.
<h1>Create new account</h1> <form action="/newaccount" method=post 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-point length of the
value of the element's value
attribute must be equal to or less than the element's maximum
allowed value length.
The following extract shows how a messaging client's text entry could be arbitrarily restricted to a fixed number of characters, thus forcing any conversation through this medium to be terse and discouraging intelligent discourse.
What are you doing? <input name=status maxlength=140>
pattern
attributeThe pattern
attribute specifies a regular expression against which the control's
value, 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.
This implies that the regular expression language
used for this attribute is the same as that used in JavaScript,
except that the pattern
attribute must match the entire value, not just any subset (somewhat
as if it implied a ^(?:
at the start of the
pattern and a )$
at the end).
When an input
element has a pattern
attribute specified,
authors should include a title
attribute to give a description of the pattern. User agents may use
the contents of this attribute, if it is present, when informing the
user that the pattern is not matched, or at any other suitable time,
such as in a tooltip or read out by assistive technology when the
control gains focus.
For example, the following snippet:
<label> Part number: <input pattern="[0-9][A-Z]{3}" name="part" title="A part number is a digit followed by three uppercase letters."/> </label>
...could cause the UA to display an alert such as:
A part number is a digit followed by three uppercase letters. You cannot 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.
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. A hint could be a sample
value or a brief description of the expected format. The attribute,
if specified, must have a value that contains no U+000A LINE FEED
(LF) or U+000D CARRIAGE RETURN (CR) characters.
For a longer hint or other advisory text, the title
attribute is more appropriate.
The placeholder
attribute should not be used as an alternative to a
label
.
User agents should present this hint to the user, after having stripped line breaks from it, when the element's value is the empty string and the control is not focused (e.g. by displaying it inside a blank unfocused control).
Here is an example of a mail configuration user interface that
uses the placeholder
attribute:
<fieldset> <legend>Mail Account</legend> <p><label>Name: <input type="text" name="fullname" placeholder="John Ratzenberger"></label></p> <p><label>Address: <input type="email" name="address" placeholder="john@example.net"></label></p> <p><label>Password: <input type="password" name="password"></label></p> <p><label>Description: <input type="text" name="desc" placeholder="My Email Account"></label></p> </fieldset>
input
element APIsvalue
[ = value ]Returns the current value of the form control.
Can be set, to change the value.
Throws an INVALID_STATE_ERR
exception if it is
set to any value other than the empty string when the control is a
file upload control.
checked
[ = value ]Returns the current checkedness of the form control.
Can be set, to change the checkedness.
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 INVALID_STATE_ERR
exception if the
control isn't date- or time-based.
valueAsNumber
[ = value ]Returns a number representing the form control's value, if applicable; otherwise, returns null.
Can be set, to change the value.
Throws an INVALID_STATE_ERR
exception if the
control is neither date- or time-based nor numeric.
stepUp
( [ n ] )stepDown
( [ n ] )Changes the form control's value by the value given in the
step
attribute, multiplied by
n. The default value for n
is 1.
Throws INVALID_STATE_ERR
exception if the control
is neither date- or time-based nor numeric, if the step
attribute's value is "any
", if the current value could not be parsed, or if
stepping in the given direction by the given amount would take the
value out of range.
list
Returns the datalist
element indicated by the
list
attribute.
selectedOption
Returns the option
element from the
datalist
element indicated by the list
attribute that matches the
form control's value.
The value
IDL
attribute allows scripts to manipulate the value of an input
element. The attribute is in one of the following modes, which
define its behavior:
type
attribute's current state
defines one.value
attribute, it must return
that attribute's value; otherwise, it must return the empty
string. On setting, it must set the element's value
attribute to the new
value.value
attribute, it must return
that attribute's value; otherwise, it must return the string "on
". On setting, it must set the element's value
attribute to the new
value.C:\fakepath\
" followed by the filename of the first
file in the list of selected files, if
any, or the empty string if the list is empty. On setting, if the
new value is the empty string, it must empty the list of selected files;
otherwise, it must throw an INVALID_STATE_ERR
exception.The checked
IDL
attribute allows scripts to manipulate the checkedness of an
input
element. On getting, it must return the current
checkedness of the element;
and on setting, it must set the element's checkedness to the new value and
set the element's dirty checkedness
flag to true.
The files
IDL
attribute allows scripts to access the element's selected files. On
getting, if the IDL attribute applies, it must return a
FileList
object that represents the current selected files. The
same object must be returned until the list of selected files
changes. If the IDL attribute does not apply, then it must instead
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 INVALID_STATE_ERR
exception; otherwise, if
the new value is null, then set the value of the element to the empty
string; otherwise, run the algorithm to convert a
Date
object to a string, as defined for that
state, on the new value, and set the value of the element to resulting
string.
The valueAsNumber
IDL
attribute represents the value
of the element, interpreted as a number.
On getting, if the valueAsNumber
attribute does
not apply, as defined for the input
element's type
attribute's current state, then
return a Not-a-Number (NaN) value. Otherwise, if the valueAsDate
attribute applies, run the algorithm to convert a
string to a Date
object defined for that state;
if the algorithm returned a Date
object, then return
the time value of the object (the number of milliseconds from
midnight UTC the morning of 1970-01-01 to the time represented by
the Date
object), otherwise, return a Not-a-Number
(NaN) value. Otherwise, run the algorithm to convert a
string to a number defined for that state; if the algorithm
returned a number, then return it, otherwise, return a Not-a-Number
(NaN) value.
On setting, if the valueAsNumber
attribute does
not apply, as defined for the input
element's type
attribute's current state, then
throw an INVALID_STATE_ERR
exception. Otherwise, if
the valueAsDate
attribute applies, run the algorithm to convert a
Date
object to a string defined for that state,
passing it a Date
object whose time value is the
new value, and set the value
of the element to resulting string. Otherwise, run the algorithm to convert a
number to a string, as defined for that state, on the new
value, and set the value of
the element to resulting string.
The stepDown(n)
and stepUp(n)
methods, when invoked, must run the
following algorithm:
If the stepDown()
and
stepUp()
methods do not
apply, as defined for the input
element's type
attribute's current state, then
throw an INVALID_STATE_ERR
exception, and abort these
steps.
If the element has no allowed value step, then throw an
INVALID_STATE_ERR
exception, and abort these
steps.
If applying the algorithm to convert a
string to a number to the string given by the element's
value results in an error,
then throw an INVALID_STATE_ERR
exception, and abort
these steps; otherwise, let value be the result
of that algorithm.
Let n be the argument, or 1 if the argument was omitted.
Let delta be the allowed value step multiplied by n.
If the method invoked was the stepDown()
method, negate delta.
Let value be the result of adding delta to value.
If the element has a minimum, and the value is less than that minimum, then throw a
INVALID_STATE_ERR
exception.
If the element has a maximum, and the value is greater than that maximum, then throw a
INVALID_STATE_ERR
exception.
Let value as string be the result of
running the algorithm to convert a
number to a string, as defined for the input
element's type
attribute's
current state, on value.
Set the value of the element to value as string.
The list
IDL
attribute must return the current suggestions source element, if
any, or null otherwise.
The selectedOption
IDL attribute must return the value determined by the following
steps:
If there is no suggestions
source element (e.g. because the list
attribute doesn't apply or is
not specified), then return null and abort these steps.
If the multiple
attribute is specified and applies, then return null and abort
these steps. (The selectedOption
IDL
attribute doesn't apply.)
Return the first option
element, in tree
order, to be a child of the suggestions source element and
whose value matches the
input
element's value, if any. If the suggestions source element
contains no matching option
element, then return null
instead.
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.