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.
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>
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.
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 not mutable.
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>
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>
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
titles as if an error has necessarily occurred.
min and max attributesThe min and max attributes indicate the allowed range of values for
the element.
Their syntax is defined by the section that defines the type attribute's current state.
If the element has a min attribute, and the result of
applying the algorithm to convert a string to a
number to the value of the min attribute is a number,
then that number is the element's minimum; otherwise, if the
type attribute's current state defines a default minimum, then that is the minimum; otherwise, the element has no minimum.
Constraint validation: When the element has a minimum, and the result of applying the algorithm to convert a string to a number to the string given by the element's value is a number, and the number obtained from that algorithm is less than the minimum, the element is suffering from an underflow.
The min attribute also defines the step base.
If the element has a max attribute, and the result of
applying the algorithm to convert a string to a
number to the value of the max attribute is a number,
then that number is the element's maximum; otherwise, if the
type attribute's current state defines a default maximum, then that is the maximum; otherwise, the element has no maximum.
Constraint validation: When the element has a maximum, and the result of applying the algorithm to convert a string to a number to the string given by the element's value is a number, and the number obtained from that algorithm is more than the maximum, the element is suffering from an overflow.
The max attribute's value (the maximum) must not be less than the min attribute's value (its minimum).
If an element has a maximum that is less than its minimum, then so long as the element has a value, it will either be suffering from an underflow or suffering from an overflow.
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 value returned by the following algorithm:
If the element has a min content attribute, and the
result of applying the algorithm to convert a
string to a number to the value of the min content
attribute is not an error, then return that result and abort these steps.
If the element has a value content attribute, and
the result of applying the algorithm to convert a
string to a number to the value of the value content
attribute is not an error, then return that result and abort these steps.
If a default step base is defined for
this element given its type attribute's state, then return
it and abort these steps.
Return zero.
Constraint validation: When the element has an allowed value step, and the result of applying the algorithm to convert a string to a number to the string given by the element's value is a number, and that number subtracted from the step base is not an integral multiple of the allowed value step, the element is suffering from a step mismatch.
The following range control only accepts values in the range 0..1, and allows 256 steps in that range:
<input name=opacity type=range min=0 max=1 step=0.00392156863>
The following control allows any time in the day to be selected, with any accuracy (e.g. thousandth-of-a-second accuracy or more):
<input name=favtime type=time step=any>
Normally, time controls are limited to an accuracy of one minute.
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.
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 U+000A LINE FEED (LF) or
U+000D CARRIAGE RETURN (CR) 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 or the control is not focused (or both), 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.
filesReturns 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. Setting this to NaN will set the underlying value to the empty string.
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, or if the step attribute's value is "any".
listReturns 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
name 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 the 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 new value is infinite, then throw a TypeError exception.
Otherwise, 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 new value is a Not-a-Number (NaN) value, then set the value of the element to the empty string. 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 the 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 the 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 the element has a minimum and a maximum and the minimum is greater than the maximum, then abort these steps.
If the element has a minimum and a maximum and there is no value greater than or equal to the element's minimum and less than or equal to the element's maximum that, when subtracted from the step base, is an integral multiple of the allowed value step, then abort these steps.
If applying the algorithm to convert a string to a number to the string given by the element's value does not result in an error, then let value be the result of that algorithm. Otherwise, let value be zero.
If value subtracted from the step
base is not an integral multiple of the allowed value
step, then set value to the nearest value that, when subtracted from
the step base, is an integral multiple of the allowed value step, and that is less than value if the method invoked was the stepDown() and more than value
otherwise.
Otherwise (value subtracted from the step base is an integral multiple of the allowed value step), run the following substeps:
Let n be the argument.
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 value is less than that minimum, then set value to the smallest value that, when subtracted from the step base, is an integral multiple of the allowed value step, and that is more than or equal to minimum.
If the element has a maximum, and value is greater than that maximum, then set value to the largest value that, when subtracted from the step base, is an integral multiple of the allowed value step, and that is less than or equal to maximum.
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.
A third example of a user interface with a commit action would be a Range controls that use a slider. While the user is dragging
the control's knob, input events would fire whenever the position
changed, whereas the change event would only fire when the user
let go of the knob, committing to a specific value.
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.