A form-associated element can have a relationship with a form
element, which is called the element's form owner. If a form-associated element is not associated with a form
element, its form owner is said to be null.
A form-associated element is, by default, associated with its ancestor form
element, but may have a form
attribute specified to override this.
This feature allows authors to work around the lack of support for nested form
elements.
If a form-associated element has a form
attribute specified, then that attribute's value must be the ID of a form
element in the element's owner Document
.
form
Returns the element's form owner.
Returns null if there isn't one.
The name
content attribute gives the name of the form control, as used in form submission and in the form
element's elements
object. If the attribute is specified, its value must not be the empty string.
Any non-empty value for name
is allowed, but the names "_charset_
" and "isindex
" are special:
isindex
This value, if used as the name of a Text control that is the first control in a form that is submitted using the application/x-www-form-urlencoded
mechanism, causes the submission to only include the value of this control, with no name.
_charset_
This value, if used as the name of a value
attribute, is automatically given a value during submission consisting of the submission character encoding.
The name
IDL attribute must reflect the name
content attribute.
The disabled
content attribute is a boolean attribute.
A form control is disabled if its disabled
attribute is set, or if it is a descendant of a fieldset
element whose disabled
attribute is set and is not a descendant of that fieldset
element's first legend
element child, if any.
The disabled
IDL attribute must reflect the disabled
content attribute.
The autofocus
content attribute allows the author to indicate that a control is to be focused as soon as the page is loaded, allowing the user to just start typing without having to manually focus the main control.
The autofocus
attribute is a boolean attribute.
There must not be more than one element in the document with the autofocus
attribute specified.
The autofocus
IDL attribute must reflect the content attribute of the same name.
In the following snippet, the text control would be focused when the document was loaded.
<input maxlength="256" name="q" value="" autofocus> <input type="submit" value="Search">
A form control maxlength
attribute, controlled by a dirty value flag, declares a limit on the number of characters a user can input.
If an element has its form control maxlength
attribute specified, the attribute's value must be a valid non-negative integer. If the attribute is specified and applying the rules for parsing non-negative integers to its value results in a number, then that number is the element's maximum allowed value length. If the attribute is omitted or parsing its value results in an error, then there is no maximum allowed value length.
Attributes for form submission can be specified both on form
elements and on submit buttons (elements that represent buttons that submit forms, e.g. an input
element whose type
attribute is in the Submit Button state).
The attributes for form submission that may be specified on form
elements are action
, enctype
, method
, novalidate
, and target
.
The corresponding attributes for form submission that may be specified on submit buttons are formaction
, formenctype
, formmethod
, formnovalidate
, and formtarget
. When omitted, they default to the values given on the corresponding attributes on the form
element.
The action
and formaction
content attributes, if specified, must have a value that is a valid non-empty URL potentially surrounded by spaces.
The action of an element is the value of the element's formaction
attribute, if the element is a submit button and has such an attribute, or the value of its form owner's action
attribute, if it has one, or else the empty string.
The method
and formmethod
content attributes are enumerated attributes with the following keywords and states:
get
, mapping to the state GET, indicating the HTTP GET method.post
, mapping to the state POST, indicating the HTTP POST method.The missing value default for these attributes is the GET state.
The method of an element is one of those states. If the element is a submit button and has a formmethod
attribute, then the element's method is that attribute's state; otherwise, it is the form owner's method
attribute's state.
The enctype
and formenctype
content attributes are enumerated attributes with the following keywords and states:
application/x-www-form-urlencoded
" keyword and corresponding state.multipart/form-data
" keyword and corresponding state.text/plain
" keyword and corresponding state.The missing value default for these attributes is the application/x-www-form-urlencoded
state.
The enctype of an element is one of those three states. If the element is a submit button and has a formenctype
attribute, then the element's enctype is that attribute's state; otherwise, it is the form owner's enctype
attribute's state.
The target
and formtarget
content attributes, if specified, must have values that are valid browsing context names or keywords.
The target of an element is the value of the element's formtarget
attribute, if the element is a submit button and has such an attribute; or the value of its form owner's target
attribute, if it has such an attribute; or, if the Document
contains a base
element with a target
attribute, then the value of the target
attribute of the first such base
element; or, if there is no such element, the empty string.
The novalidate
and formnovalidate
content attributes are boolean attributes. If present, they indicate that the form is not to be validated during submission.
The no-validate state of an element is true if the element is a submit button and the element's formnovalidate
attribute is present, or if the element's form owner's novalidate
attribute is present, and false otherwise.
This attribute is useful to include "save" buttons on forms that have validation constraints, to allow users to save their progress even though they haven't fully entered the data in the form. The following example shows a simple form that has two required fields. There are three buttons: one to submit the form, which requires both fields to be filled in; one to save the form so that the user can come back and fill it in later; and one to cancel the form altogether.
<form action="editor.cgi" method="post"> <p><label>Name: <input required name=fn></label></p> <p><label>Essay: <textarea required name=essay></textarea></label></p> <p><input type=submit name=submit value="Submit essay"></p> <p><input type=submit formnovalidate name=save value="Save essay"></p> <p><input type=submit formnovalidate name=cancel value="Cancel"></p> </form>
The action
IDL attribute must reflect the content attribute of the same name, except that on getting, when the content attribute is missing or its value is the empty string, the document's address must be returned instead. The target
IDL attribute must reflect the content attribute of the same name. The method
and enctype
IDL attributes must reflect the
respective content attributes of the same name, limited to only known values. The encoding
IDL attribute must reflect the enctype
content attribute, limited to only known values. The noValidate
IDL attribute
must reflect the novalidate
content attribute. The formAction
IDL attribute must reflect the formaction
content attribute, except that on getting, when the content attribute is missing or its value is the empty string, the document's address must be returned instead. The formEnctype
IDL attribute must reflect the formenctype
content attribute, limited to only known values. The formMethod
IDL attribute must reflect the formmethod
content attribute, limited to only known values. The formNoValidate
IDL attribute must reflect the formnovalidate
content attribute. The formTarget
IDL attribute must reflect the formtarget
content attribute.
A form control dirname
attribute on a form control element enables the submission of the directionality of the element, and gives the name of the field that contains this value during form submission. If such an attribute is specified, its value must not be the empty string.
The input
and textarea
elements define the following members in their DOM interfaces for handling their selection:
void select(); attribute unsigned long selectionStart; attribute unsigned long selectionEnd; attribute DOMString selectionDirection; void setSelectionRange(in unsigned long start, in unsigned long end, in optional DOMString direction);
These methods and attributes expose and control the selection of input
and textarea
text fields.
select
()Selects everything in the text field.
selectionStart
[ = value ]Returns the offset to the start of the selection.
Can be set, to change the start of the selection.
selectionEnd
[ = value ]Returns the offset to the end of the selection.
Can be set, to change the end of the selection.
selectionDirection
[ = value ]Returns the current direction of the selection.
Can be set, to change the direction of the selection.
The possible values are "forward
", "backward
", and "none
".
setSelectionRange
(start, end [, direction] )Changes the selection to cover the given substring in the given direction. If the direction is omitted, it will be reset to be the platform default (none or forward).
Characters with no visible rendering, such as U+200D ZERO WIDTH JOINER, still count as characters. Thus, for instance, the selection can include just an invisible character, and the text insertion cursor can be placed to one side or another of such a character.
To obtain the currently selected text, the following JavaScript suffices:
var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);
To add some text at the start of a text control, while maintaining the text selection, the three attributes must be preserved:
var oldStart = control.selectionStart; var oldEnd = control.selectionEnd; var oldDirection = control.selectionDirection; var prefix = "http://"; control.value = prefix + control.value; control.setSelectionRange(oldStart + prefix.length, oldEnd + prefix.length, oldDirection);
willValidate
Returns true if the element will be validated when the form is submitted; false otherwise.
setCustomValidity
(message)Sets a custom error, so that the element would fail to validate. The given message is the message to be shown to the user when reporting the problem to the user.
If the argument is the empty string, clears the custom error.
validity
. valueMissing
Returns true if the element has no value but is a required field; false otherwise.
validity
. typeMismatch
Returns true if the element's value is not in the correct syntax; false otherwise.
validity
. patternMismatch
Returns true if the element's value doesn't match the provided pattern; false otherwise.
validity
. tooLong
Returns true if the element's value is longer than the provided maximum length; false otherwise.
validity
. rangeUnderflow
Returns true if the element's value is lower than the provided minimum; false otherwise.
validity
. rangeOverflow
Returns true if the element's value is higher than the provided maximum; false otherwise.
validity
. stepMismatch
Returns true if the element's value doesn't fit the rules given by the step
attribute; false otherwise.
validity
. customError
Returns true if the element has a custom error; false otherwise.
validity
. valid
Returns true if the element's value has no validity problems; false otherwise.
checkValidity
()Returns true if the element's value has no validity problems; false otherwise. Fires an invalid
event at the element in the latter case.
validationMessage
Returns the error message that would be shown to the user if the element was to be checked for validity.
In the following example, a script checks the value of a form control each time it is edited, and whenever it is not a valid value, uses the setCustomValidity()
method to set an appropriate message.
<label>Feeling: <input name=f type="text" oninput="check(this)"></label> <script> function check(input) { if (input.value == "good" || input.value == "fine" || input.value == "tired") { input.setCustomValidity('"' + input.value + '" is not a feeling.'); } else { // input is fine -- reset the error message input.setCustomValidity(''); } } </script>
The validity
attribute must return a ValidityState
object that represents the validity states of the element. This object is live, and the same object must be returned each time the element's validity
attribute is retrieved.
Servers should not rely on client-side validation. Client-side validation can be intentionally bypassed by hostile users, and unintentionally bypassed by users of older user agents or automated tools that do not implement these features. The constraint validation features are only intended to improve the user experience, not to provide any kind of security mechanism.
When a form is submitted, the data in the form is converted into the structure specified by the enctype, and then sent to the destination specified by the action using the given method.
For example, take the following form:
<form action="/find.cgi" method=get> <input type=text name=t> <input type=search name=q> <input type=submit> </form>
If the user types in "cats" in the first field and "fur" in the second, and then hits the submit button, then the user agent will load /find.cgi?t=cats&q=fur
.
On the other hand, consider this form:
<form action="/find.cgi" method=post enctype="multipart/form-data"> <input type=text name=t> <input type=search name=q> <input type=submit> </form>
Given the same user input, the result on submission is quite different: the user agent instead does an HTTP POST to the given URL, with as the entity body something like the following text:
------kYFrd4jNJEgCervE Content-Disposition: form-data; name="t" cats ------kYFrd4jNJEgCervE Content-Disposition: form-data; name="q" fur ------kYFrd4jNJEgCervE--