HTMLFormElement

Jump to:
  1. Properties
  2. Methods
  3. Usage notes
  4. Examples
  5. Specifications
  6. Browser compatibility
  7. See also

The HTMLFormElement interface represents a <form> element in the DOM; it can be used to access and in some cases modify aspects of the form, as well as access its component elements.

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.lengthRead only
A long reflecting  the number of controls in the form.
HTMLFormElement.name
A DOMString reflecting the value of the form's name HTML attribute, containing the name of the form.
HTMLFormElement.method
A DOMString reflecting the value of the form's method 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's target HTML attribute, indicating where to display the results received from submitting the form.
HTMLFormElement.action
A DOMString reflecting the value of the form's action HTML attribute, containing the URI of a program that processes the information submitted by the form.
HTMLFormElement.encoding or HTMLFormElement.enctype
A DOMString reflecting the value of the form's enctype 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's accept-charset HTML attribute, representing the character encoding that the server accepts.
HTMLFormElement.autocomplete
A DOMString reflecting the value of the form's autocomplete 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's  novalidate 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; returns false if some controls do not satisfy their constraints. Fires an event named 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.
HTMLFormElement.reportValidity()
Returns true if the element's child controls satisfy their validation constraints. When false is returned, cancelable invalid 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 or on. The form will receive an event once the user has finished with the interface, the event will either be autocomplete when the fields have been filled or autocompleteerror when there was a problem. This method has been removed from Chrome and Firefox — see bug 1270740 for background information on why.

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 is name.

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.

Elements that are considered form controls

The elements which are included by HTMLFormElement.elements and HTMLFormElement.length are:

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

Create a new form element, modify its attributes and submit 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" id="formA" action="/cgi-bin/test" method="POST">
 <p>Click "Info" for form details; "Set" to change settings.</p>
 <p>
  <input type="button" value="info" onclick="getFormInfo();">
  <input type="button" value="set"  onclick="setFormInfo(this.form);">
  <input type="reset" value="reset"><br>
  <textarea id="tex" style="height:15em; width:20em"></textarea>
 </p>
</form>

<script type="text/javascript">
  function getFormInfo(){
    var info;
    var f = document.forms["formA"]; //Get a reference to the form via id.
    info = "elements: " + f.elements     + "\n"
         + "length: "   + f.length       + "\n"
         + "name: "     + f.name         + "\n"
         + "charset: "  + f.acceptCharset+ "\n"
         + "action: "   + f.action       + "\n"
         + "enctype: "  + f.enctype      + "\n"
         + "encoding: " + f.encoding     + "\n"
         + "method: "   + f.method       + "\n"
         + "target: "   + f.target;
    document.forms["formA"].elements['tex'].value = info;
  }
  function setFormInfo(f){ //Argument is a reference to the form.
    f.method = "GET";
    f.action = "/cgi-bin/evil_executable.cgi";
    f.name   = "totally_new";
  }
</script>

Submit a form in a popup window:

<!doctype html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>MDN Example</title>
<script type="text/javascript">
function popupSend (oFormElement) {
  if (oFormElement.method && oFormElement.method.toLowerCase() !== "get") {
    console.error("This script supports the GET method only.");
    return;
  }
  var oField, sFieldType, nFile, sSearch = "";
  for (var nItem = 0; nItem < oFormElement.elements.length; nItem++) {
    oField = oFormElement.elements[nItem];
    if (!oField.hasAttribute("name")) { continue; }
    sFieldType = oField.nodeName.toUpperCase() === "INPUT" ? oField.getAttribute("type").toUpperCase() : "TEXT";
    if (sFieldType === "FILE") {
      for (nFile = 0; nFile < oField.files.length; sSearch += "&" + escape(oField.name) + "=" + escape(oField.files[nFile++].name));
    } else if ((sFieldType !== "RADIO" && sFieldType !== "CHECKBOX") || oField.checked) {
      sSearch += "&" + escape(oField.name) + "=" + escape(oField.value);
    }
  }
  open(oFormElement.action.replace(/(?:\?.*)?$/, sSearch.replace(/^&/, "?")), "submit-" + (oFormElement.name || Math.floor(Math.random() * 1e6)), "resizable=yes,scrollbars=yes,status=yes");
}
</script>

</head>
 
<body>

<form name="yourForm" action="test.php" method="get" onsubmit="popupSend(this); return false;">
  <p>First name: <input type="text" name="firstname" /><br />
  Last name: <input type="text" name="lastname" /><br />
  Password: <input type="password" name="pwd" /><br />
  <input type="radio" name="sex" value="male" /> Male <input type="radio" name="sex" value="female" /> Female</p>
  <p><input type="checkbox" name="vehicle" value="Bike" />I have a bike<br />
  <input type="checkbox" name="vehicle" value="Car" />I have a car</p>
  <p><input type="submit" value="Submit" /></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

FeatureChromeEdgeFirefoxInternet ExplorerOperaSafari
Basic support Yes Yes1 Yes Yes Yes
reportValidity40 ?49 No Yes Yes
FeatureAndroid webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
Basic support Yes Yes Yes Yes Yes Yes ?
reportValidity4040 ? ? ? ? ?

See also

  • The HTML element implementing this interface: <form>.

Document Tags and Contributors

Tags: 
 Contributors to this page: fscholz, Sheppy, chrisdavidmills, Ephys, Sebastianz, trusktr, erikadoyle, Lcng, shtarbanov, slimsag, jonathanKingston, teoli, jpmedley, kscarfone, ethertank, fusionchess, jswisher, Brettz9, WEStafford, Mgjbot, Asztal, Takenbot, RobG, William E, GSchizas, Dria
 Last updated by: fscholz,