This is a work in progress! For the latest updates from the HTML WG, possibly including important bug fixes, please look at the editor's draft instead. There may also be a more up-to-date Working Draft with changes based on resolution of Last Call issues.
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.
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,
readonly,
required, and
step content attributes;
list,
value,
valueAsNumber, and
selectedOption 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() and
setSelectionRange() methods.
The input element represents a control
for setting the element's value to a string representing a
number, but with the caveat that the exact value is not important,
letting UAs provide a simpler interface than they do for the Number state.
In this state, the range and step constraints are enforced even during user input, and there is no way to set the value to the empty string.
If the element is mutable, the user agent should allow the user to change the number represented by its value, as obtained from applying the rules for parsing floating point number values to it. User agents must not allow the user to set the value to a string that is not a valid floating point number. If the user agent provides a user interface for selecting a number, then the value must be set to a best representation of the 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,
valueAsNumber, and
selectedOption 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() 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 similiarly 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.
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,
value, and
selectedOption 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,
maxlength,
max,
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(),
setSelectionRange(),
stepDown(), and
stepUp() methods.
The input element represents a
two-state control that represents the element's checkedness state. If the
element's checkedness state
is true, the control represents a positive selection, and if it is
false, a negative selection. If the element's indeterminate 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.
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,
selectedOption,
selectionStart,
selectionEnd,
selectionDirection,
valueAsDate, and
valueAsNumber IDL attributes;
select(),
setSelectionRange(),
stepDown(), and
stepUp() methods.
The input event does not apply.
When an input element's type attribute is in the Radio Button state, the rules
in this section apply.
The input element represents a control
that, when used in conjunction with other input
elements, forms a radio button group in which only one
control can have its checkedness state set to true. If
the element's checkedness
state is true, the control represents the selected control in the
group, and if it is false, it indicates a control in the group that
is not selected.
The radio button group that contains an
input element a also contains all
the other input elements b that
fulfill all of the following conditions:
input element b's type attribute is in the Radio Button state.name
attribute, 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. .
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,
selectedOption,
selectionStart,
selectionEnd,
selectionDirection,
valueAsDate, and
valueAsNumber IDL attributes;
select(),
setSelectionRange(),
stepDown(), and
stepUp() methods.
The input event does not apply.
When an input element's type attribute is in the File Upload state, the rules in this
section apply.
The input element represents a list of
selected files,
each file consisting of a file name, a file type, and a file body
(the contents of the file).
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 REVERSE SOLIDUS 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.
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) { var x;
x = path.lastIndexOf('\\');
if (x >= 0) // Windows-based path
return path.substr(x+1);
x = path.lastIndexOf('/');
if (x >= 0) // Unix-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,
selectedOption,
selectionStart,
selectionEnd,
selectionDirection,
valueAsDate, and
valueAsNumber IDL attributes;
select(),
setSelectionRange(),
stepDown(), and
stepUp() methods.
The input event does not apply.
When an input element's type attribute is in the Submit Button state, the rules
in this section apply.
The input element represents a button
that, when activated, submits the form. If the
element has a value attribute,
the button's label must be the value of that attribute; otherwise,
it must be an implementation-defined string that means "Submit" or
some such. The element is a button, specifically a submit button.
If the element is mutable, the user agent should allow the user to activate the element.
The element's activation behavior, if the element
has a form owner, is to submit the form
owner from the input element; otherwise, it is
to do nothing.
The formaction, formenctype, formmethod, formnovalidate, and formtarget attributes are attributes
for form submission.
The 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,
selectedOption,
selectionStart,
selectionEnd,
selectionDirection,
valueAsDate, and
valueAsNumber IDL attributes;
select(),
setSelectionRange(),
stepDown(), and
stepUp() methods.
When an input element's type attribute is in the Image Button state, the rules
in this section apply.
The input element represents either an
image from which a user can select a coordinate and submit the form,
or alternatively a button from which the user can submit the
form. The element is a button,
specifically a submit
button.
The image is given by the src attribute. The src attribute must be present, and
must contain a valid 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 alternative button for users and
user agents who cannot use the image. The alt attribute must also be present,
and must contain a non-empty string.
The input element supports dimension
attributes.
If the src attribute is set,
and the image is available and
the user agent is configured to display that image, then: The
element represents a control for selecting a coordinate from
the image specified by the src
attribute; if the element is mutable, the user agent should
allow the user to select this coordinate. The
activation behavior in this case consists of taking the
user's selected coordinate, and
then, if the element has a form owner, submitting the input
element's form owner from the input
element. If the user activates the control without explicitly
selecting a coordinate, then the coordinate (0,0) must be
assumed.
Otherwise, the element represents a submit button
whose label is given by the value of the alt attribute; if the element is mutable, the user agent should
allow the user to activate the button. The activation
behavior in this case consists of setting the selected
coordinate to (0,0), and then, if the element has a
form owner, submitting the input
element's form owner from the input
element.
The selected coordinate must consist of an x-component and a y-component. The coordinates represent the position relative to the edge of the image, with the coordinate space having the positive x direction to the right, and the positive y direction downwards.
The x-component must be a valid integer representing a number x in the range −(borderleft+paddingleft) ≤ x ≤ width+borderright+paddingright, where width is the rendered width of the image, borderleft is the width of the border on the left of the image, paddingleft is the width of the padding on the left of the image, borderright is the width of the border on the right of the image, and paddingright is the width of the padding on the right of the image, with all dimensions given in CSS pixels.
The y-component must be a valid integer representing a number y in the range −(bordertop+paddingtop) ≤ y ≤ height+borderbottom+paddingbottom, where height is the rendered height of the image, bordertop is the width of the border above the image, paddingtop is the width of the padding above the image, borderbottom is the width of the border below the image, and paddingbottom is the width of the padding below the image, with all dimensions given in CSS pixels.
Where a border or padding is missing, its width is zero CSS pixels.
The formaction, formenctype, formmethod, formnovalidate, and formtarget attributes are attributes
for form submission.
The following common input element content
attributes and IDL attributes apply to the element:
alt,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
src, and
width content attributes;
value IDL attribute.
The value IDL attribute is
in mode default.
The following content attributes must not be specified and do not
apply to the element:
accept,
autocomplete,
checked,
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,
selectedOption,
selectionStart,
selectionEnd,
selectionDirection,
valueAsDate, and
valueAsNumber IDL attributes;
select(),
setSelectionRange(),
stepDown(), and
stepUp() methods.
Many aspects of this state's behavior are similar to
the behavior of the img element. Readers are encouraged
to read that section, where many of the same requirements are
described in more detail.
When an input element's type attribute is in the Reset Button state, the rules
in this section apply.
The input element represents a button
that, when activated, resets the form. If the
element has a value attribute,
the button's label must be the value of that attribute; otherwise,
it must be an implementation-defined string that means "Reset" or
some such. The element is a button.
If the element is mutable, the user agent should allow the user to activate the element.
The element's activation behavior, if the element has a form owner, is to reset the form owner; otherwise, it is to do nothing.
Constraint validation: The element is barred from constraint validation.
The value IDL attribute
applies to this element and is in mode default.
The following content attributes must not be specified and do not
apply to the element:
accept,
alt,
autocomplete,
checked,
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,
selectedOption,
selectionStart,
selectionEnd,
selectionDirection,
valueAsDate, and
valueAsNumber IDL attributes;
select(),
setSelectionRange(),
stepDown(), and
stepUp() methods.
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 user agent should allow the user to activate the element. The element's activation behavior is to do nothing.
Constraint validation: The element is barred from constraint validation.
The value IDL attribute
applies to this element and is in mode default.
The following content attributes must not be specified and do not
apply to the element:
accept,
alt,
autocomplete,
checked,
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,
selectedOption,
selectionStart,
selectionEnd,
selectionDirection,
valueAsDate, and
valueAsNumber IDL attributes;
select(),
setSelectionRange(),
stepDown(), and
stepUp() methods.