You’re reading the English version of this content since no translation exists yet for this locale. Help us translate this article!
The HTMLFormElement
interface represents a <form>
element in the DOM; it allows access to and in some cases modification of aspects of the form, as well as access to its component elements.
<div id="interfaceDiagram" style="display: inline-block; position: relative; width: 100%; padding-bottom: 20%; vertical-align: middle; overflow: hidden;"><svg style="display: inline-block; position: absolute; top: 0; left: 0;" viewbox="-50 0 600 120" preserveAspectRatio="xMinYMin meet"><a xlink:href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget" target="_top"><rect x="1" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text x="56" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">EventTarget</text></a><polyline points="111,25 121,20 121,30 111,25" stroke="#D4DDE4" fill="none"/><line x1="121" y1="25" x2="151" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/en-US/docs/Web/API/Node" target="_top"><rect x="151" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text x="188.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">Node</text></a><polyline points="226,25 236,20 236,30 226,25" stroke="#D4DDE4" fill="none"/><line x1="236" y1="25" x2="266" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/en-US/docs/Web/API/Element" target="_top"><rect x="266" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text x="303.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">Element</text></a><polyline points="341,25 351,20 351,30 341,25" stroke="#D4DDE4" fill="none"/><line x1="351" y1="25" x2="381" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement" target="_top"><rect x="381" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text x="436" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">HTMLElement</text></a><polyline points="491,25 501,20 501,30 491,25" stroke="#D4DDE4" fill="none"/><line x1="501" y1="25" x2="509" y2="25" stroke="#D4DDE4"/><line x1="509" y1="25" x2="509" y2="90" stroke="#D4DDE4"/><line x1="509" y1="90" x2="492" y2="90" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement" target="_top"><rect x="341" y="65" width="150" height="50" fill="#F4F7F8" stroke="#D4DDE4" stroke-width="2px" /><text x="416" y="94" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">HTMLFormElement</text></a></svg></div>
a:hover text { fill: #0095DD; pointer-events: all;}
Properties
This interface also inherits properties from its parent, HTMLElement
.
HTMLFormElement.elements
Read only- A
HTMLFormControlsCollection
holding all form controls belonging to this form element. HTMLFormElement.length
Read only- A
long
reflecting the number of controls in the form. HTMLFormElement.name
- A
DOMString
reflecting the value of the form'sname
HTML attribute, containing the name of the form. HTMLFormElement.method
- A
DOMString
reflecting the value of the form'smethod
HTML attribute, indicating the HTTP method used to submit the form. Only specified values can be set. HTMLFormElement.target
- A
DOMString
reflecting the value of the form'starget
HTML attribute, indicating where to display the results received from submitting the form. HTMLFormElement.action
- A
DOMString
reflecting the value of the form'saction
HTML attribute, containing the URI of a program that processes the information submitted by the form. HTMLFormElement.encoding
orHTMLFormElement.enctype
- A
DOMString
reflecting the value of the form'senctype
HTML attribute, indicating the type of content that is used to transmit the form to the server. Only specified values can be set. The two properties are synonyms. HTMLFormElement.acceptCharset
- A
DOMString
reflecting the value of the form'saccept-charset
HTML attribute, representing the character encoding that the server accepts. HTMLFormElement.autocomplete
- A
DOMString
reflecting the value of the form'sautocomplete
HTML attribute, indicating whether the controls in this form can have their values automatically populated by the browser. HTMLFormElement.noValidate
- A
Boolean
reflecting the value of the form'snovalidate
HTML attribute, indicating whether the form should not be validated.
Named inputs are added to their owner form instance as properties, and can overwrite native properties if they share the same name (eg a form with an input named action
will have its action
property return that input instead of the form's action
HTML attribute).
Methods
This interface also inherits methods from its parent, HTMLElement
.
HTMLFormElement.submit()
- Submits the form to the server.
HTMLFormElement.reset()
- Resets the form to its initial state.
HTMLFormElement.checkValidity()
- Returns
true
if the element's child controls are subject to constraint validation and satisfy those contraints; returnsfalse
if some controls do not satisfy their constraints. Fires an event namedinvalid
at any control that does not satisfy its constraints; such controls are considered invalid if the event is not canceled. It is up to the programmer to decide how to respond tofalse
. HTMLFormElement.reportValidity()
- Returns
true
if the element's child controls satisfy their validation constraints. Whenfalse
is returned, cancelableinvalid
events are fired for each invalid child and validation problems are reported to the user. HTMLFormElement.requestAutocomplete()
- Triggers a native browser interface to assist the user in completing the fields which have an autofill field name value that is not
off
oron
. The form will receive an event once the user has finished with the interface, the event will either beautocomplete
when the fields have been filled orautocompleteerror
when there was a problem. This method has been removed from Chrome and Firefox — see bug 1270740 for background information on why.
Events
Listen to these events using addEventListener()
or by assigning an event listener to the oneventname
property of this interface.
formdata
formdata
event fires after the entry list representing the form's data is constructed.
Also available via theonformdata
property.
The reset
reset
event fires when a form is reset.
Also available via theonreset
property.
The submit
- The
submit
event fires when a form is submitted.
Also available via theonsubmit
property.
Usage notes
Obtaining a form element object
To obtain an HTMLFormElement
object, you can use a CSS selector with querySelector()
, or you can get a list of all of the forms in the document using its forms
property.
Document.forms
returns an array of HTMLFormElement
objects listing each of the forms on the page. You can then use any of the following syntaxes to get an individual form:
document.forms[index]
- Returns the form at the specified
index
into the array of forms. document.forms[id]
- Returns the form whose ID is
id
. document.forms[name]
- Returns the form whose
name
attribute's value isname
.
Accessing the form's elements
You can access the list of the form's data-containing elements by examining the form's elements
property. This returns an HTMLFormControlsCollection
listing all of the form's user data entry elements, both those which are descendants of the <form>
and those which are made members of the form using their form
attributes.
You can also get the form's element by using its name
attribute as a key of the form
, but using elements
is a better approach — it contains only the form's elements, and it cannot be mixed with other attributes of the form
.
Elements that are considered form controls
The elements which are included by HTMLFormElement.elements
and HTMLFormElement.length
are:
<button>
<fieldset>
<input>
(with the exception that any whosetype
is"image"
are omitted for historical reasons)<object>
<output>
<select>
<textarea>
No other elements are included in the list returned by elements
, which makes it an excellent way to get at the elements most important when processing forms.
Examples
Creating a new form element, modifying its attributes, then submitting it:
var f = document.createElement("form");// Create a form document.body.appendChild(f); // Add it to the document body f.action = "/cgi-bin/some.cgi"; // Add action and method attributes f.method = "POST"; f.submit(); // Call the form's submit method
Extract information from a form element and set some of its attributes:
<form name="formA" action="/cgi-bin/test" method="post"> <p>Press "Info" for form details, or "Set" to change those details.</p> <p> <button type="button" onclick="getFormInfo();">Info</button> <button type="button" onclick="setFormInfo(this.form);">Set</button> <button type="reset">Reset</button> </p> <textarea id="form-info" rows="15" cols="20"></textarea> </form> <script> function getFormInfo(){ // Get a reference to the form via its name var f = document.forms["formA"]; // The form properties we're interested in var properties = [ 'elements', 'length', 'name', 'charset', 'action', 'acceptCharset', 'action', 'enctype', 'method', 'target' ]; // Iterate over the properties, turning them into a string that we can display to the user var info = properties.map(function(property) { return property + ": " + f[property] }).join("\n"); // Set the form's <textarea> to display the form's properties document.forms["formA"].elements['form-info'].value = info; // document.forms["formA"]['form-info'].value would also work } function setFormInfo(f){ // Argument should be a form element reference. f.action = "a-different-url.cgi"; f.name = "a-different-name"; } </script>
Submit a form into a new window:
<!doctype html> <html> <head> <meta charset="utf-8"> <title>Example new-window form submission</title> </head> <body> <form action="test.php" target="_blank"> <p><label>First name: <input type="text" name="firstname"></label></p> <p><label>Last name: <input type="text" name="lastname"></label></p> <p><label><input type="password" name="pwd"></label></p> <fieldset> <legend>Pet preference</legend> <p><label><input type="radio" name="pet" value="cat"> Cat</label></p> <p><label><input type="radio" name="pet" value="dog"> Dog</label></p> </fieldset> <fieldset> <legend>Owned vehicles</legend> <p><label><input type="checkbox" name="vehicle" value="Bike">I have a bike</label></p> <p><label><input type="checkbox" name="vehicle" value="Car">I have a car</label></p> </fieldset> <p><button>Submit</button></p> </form> </body> </html>
Submitting forms and uploading files using XMLHttpRequest
If you want to know how to serialize and submit a form using the XMLHttpRequest
API, please read this paragraph.
Specifications
Specification | Status | Comment |
---|---|---|
HTML Living Standard The definition of 'HTMLFormElement' in that specification. |
Living Standard | The following method has been added: requestAutocomplete() . |
HTML5 The definition of 'HTMLFormElement' in that specification. |
Recommendation | The elements properties returns an HTMLFormControlsCollection instead of a raw HTMLCollection . This is mainly a technical change. The following method has been added: checkValidity() . The following properties have been added: autocomplete , noValidate , and encoding . |
Document Object Model (DOM) Level 2 HTML Specification The definition of 'HTMLFormElement' in that specification. |
Obsolete | No change |
Document Object Model (DOM) Level 1 Specification The definition of 'HTMLFormElement' in that specification. |
Obsolete | Initial definition |
Browser compatibility
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
HTMLFormElement | Chrome Full support Yes | Edge Full support Yes | Firefox Full support 1 | IE Full support Yes | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
acceptCharset | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
action | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
autocomplete | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
checkValidity | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
elements | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
encoding | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
enctype | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
length | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
method | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
name | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
noValidate | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
reportValidity | Chrome Full support 40 | Edge Full support 17 | Firefox Full support 49 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support 40 | Chrome Android Full support 40 | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support 4.0 |
requestAutocomplete | Chrome No support No | Edge ? | Firefox No support No | IE ? | Opera No support No | Safari ? | WebView Android No support No | Chrome Android No support No | Firefox Android No support No | Opera Android No support No | Safari iOS ? | Samsung Internet Android ? |
reset | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
reset event | Chrome Full support Yes | Edge Full support Yes | Firefox Full support Yes | IE Full support Yes | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
submit | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE Full support Yes | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
submit event | Chrome Full support Yes | Edge Full support Yes | Firefox Full support Yes | IE Full support Yes | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
target | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- Non-standard. Expect poor cross-browser support.
- Non-standard. Expect poor cross-browser support.
- Deprecated. Not for use in new websites.
- Deprecated. Not for use in new websites.
See also
- The HTML element implementing this interface:
<form>
.