HTML5 (Edition for Web Authors)

← 4.10.8 The button element – Table of contents – 4.11 Interactive elements →

4.10.18 Association of controls and forms

Status: Last call for comments

A form-associated element can have a relationship with a form element, which is called the element's form owner. If a form-associated element is not associated with a form element, its form owner is said to be null.

A form-associated element is, by default, associated with its nearest ancestor form element, but may have a form attribute specified to override this.

If a form-associated element has a form attribute specified, then its value must be the ID of a form element in the element's owner Document.

element . form

Returns the element's form owner.

Returns null if there isn't one.

4.10.19 Attributes common to form controls

Status: Last call for comments

4.10.19.1 Naming form controls

Status: Last call for comments

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.

4.10.19.2 Enabling and disabling form controls

Status: Last call for comments

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.

4.10.19.3 Autofocusing a form control

Status: Last call for comments

The autofocus content attribute allows the user 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.

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">

4.10.19.4 Limiting user input length

Status: Last call for comments

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.

4.10.19.5 Form submission

Status: Last call for comments

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 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:

The keyword GET, mapping to the state GET, indicating the HTTP GET method.
The keyword POST, mapping to the state POST, indicating the HTTP POST method.
The keyword PUT, mapping to the state PUT, indicating the HTTP PUT method.
The keyword DELETE, mapping to the state DELETE, indicating the HTTP DELETE method.

The missing value default for these attributes is the GET state.

The method of an element is one of those four 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:

The "application/x-www-form-urlencoded" keyword and corresponding state.
The "multipart/form-data" keyword and corresponding state.
The "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 one of the child nodes of the head element is 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 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>

4.10.20 Constraints

Status: Last call for comments

4.10.20.1 Definitions

Status: Last call for comments

4.10.20.2 The constraint validation API

Status: Last call for comments

element . willValidate

Returns true if the element will be validated when the form is submitted; false otherwise.

element . 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.

element . validity . valueMissing

Returns true if the element has no value but is a required field; false otherwise.

element . validity . typeMismatch

Returns true if the element's value is not in the correct syntax; false otherwise.

element . validity . patternMismatch

Returns true if the element's value doesn't match the provided pattern; false otherwise.

element . validity . tooLong

Returns true if the element's value is longer than the provided maximum length; false otherwise.

element . validity . rangeUnderflow

Returns true if the element's value is lower than the provided minimum; false otherwise.

element . validity . rangeOverflow

Returns true if the element's value is higher than the provided maximum; false otherwise.

element . validity . stepMismatch

Returns true if the element's value doesn't fit the rules given by the step attribute; false otherwise.

element . validity . customError

Returns true if the element has a custom error; false otherwise.

element . validity . valid

Returns true if the element's value has no validity problems; false otherwise.

valid = element . 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.

element . 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>

4.10.20.3 Security

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.

4.10.21 Form submission

Status: Last call for comments

This section is non-normative.

When forms are submitted, the data in the form is converted into the form 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--