The {{domxref("HTMLFormElement")}} interface represents a {{HTMLElement("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.
{{InheritanceDiagram(600,120)}}
This interface also inherits properties from its parent, {{domxref("HTMLElement")}}.
long reflecting the number of controls in the form.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 {{ htmlattrxref("action", "form") }} HTML attribute).
This interface also inherits methods from its parent, {{domxref("HTMLElement")}}.
true if the element's child controls are subject to constraint validation and satisfy those contraints; returns false if some controls do not satisfy their constraints. Fires an event named {{event("invalid")}} 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 to false.true if the element's child controls satisfy their validation constraints. When false is returned, cancelable {{Event("invalid")}} events are fired for each invalid child and validation problems are reported to the user.off or on. The form will receive an event once the user has finished with the interface, the event will either be {{event("autocomplete")}} when the fields have been filled or {{event("autocompleteerror")}} when there was a problem.Listen to these events using addEventListener() or by assigning an event listener to the oneventname property of this interface.
formdataformdata event fires after the entry list representing the form's data is constructed.onformdata property.resetreset event fires when a form is reset.onreset property.submitsubmit event fires when a form is submitted.onsubmit property.To obtain an HTMLFormElement object, you can use a CSS selector with {{domxref("ParentNode.querySelector", "querySelector()")}}, or you can get a list of all of the forms in the document using its {{domxref("Document.forms", "forms")}} property.
{{domxref("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]index into the array of forms.document.forms[id]id.document.forms[name]name.You can access the list of the form's data-containing elements by examining the form's {{domxref("HTMLFormElement.elements", "elements")}} property. This returns an {{domxref("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.
The elements which are included by HTMLFormElement.elements and HTMLFormElement.length are:
"image" are omitted for historical reasons)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.
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>
XMLHttpRequestIf you want to know how to serialize and submit a form using the {{domxref("XMLHttpRequest")}} API, please read this paragraph.
| Specification | Status | Comment |
|---|---|---|
| {{SpecName('HTML WHATWG', "#htmlformelement", "HTMLFormElement")}} | {{Spec2('HTML WHATWG')}} | The following method has been added: requestAutocomplete(). |
| {{SpecName('HTML5 W3C', "sec-forms.html#htmlformelement", "HTMLFormElement")}} | {{Spec2('HTML5 W3C')}} | The elements properties returns an {{domxref("HTMLFormControlsCollection")}} instead of a raw {{domxref("HTMLCollection")}}. This is mainly a technical change. The following method has been added: checkValidity(). The following properties have been added: autocomplete, noValidate, and encoding. |
{{Compat("api.HTMLFormElement")}}