path: root/files/uk/web/api/htmlformelement/index.html

---
title: HTMLFormElement
slug: Web/API/HTMLFormElement
tags:
  - API
  - Form Element
  - Forms
  - HTML DOM
  - HTML forms
  - HTMLFormElement
  - Interface
  - NeedsTranslation
  - Reference
  - TopicStub
translation_of: Web/API/HTMLFormElement
---
<div>{{APIRef("HTML DOM")}}</div>

<p><span class="seoSummary">The <code><strong>HTMLFormElement</strong></code> 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.</span></p>

<p>{{InheritanceDiagram(600,120)}}</p>

<h2 id="Properties">Properties</h2>

<p><em>This interface also inherits properties from its parent, {{domxref("HTMLElement")}}.</em></p>

<dl>
 <dt>{{domxref("HTMLFormElement.elements")}} {{ReadOnlyInline}}</dt>
 <dd>A {{domxref("HTMLFormControlsCollection")}} holding all form controls belonging to this form element.</dd>
 <dt>{{domxref("HTMLFormElement.length")}}{{ReadOnlyInline}}</dt>
 <dd>A <code>long</code> reflecting  the number of controls in the form.</dd>
 <dt>{{domxref("HTMLFormElement.name")}}</dt>
 <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("name", "form") }} HTML attribute, containing the name of the form.</dd>
 <dt>{{domxref("HTMLFormElement.method")}}</dt>
 <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("method", "form") }} HTML attribute, indicating the HTTP method used to submit the form. Only specified values can be set.</dd>
 <dt>{{domxref("HTMLFormElement.target")}}</dt>
 <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("target", "form") }} HTML attribute, indicating where to display the results received from submitting the form.</dd>
 <dt>{{domxref("HTMLFormElement.action")}}</dt>
 <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("action", "form") }} HTML attribute, containing the URI of a program that processes the information submitted by the form.</dd>
 <dt>{{domxref("HTMLFormElement.encoding")}} or {{domxref("HTMLFormElement.enctype")}}</dt>
 <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("enctype", "form") }} 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.</dd>
 <dt>{{domxref("HTMLFormElement.acceptCharset")}}</dt>
 <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("accept-charset", "form") }} HTML attribute, representing the character encoding that the server accepts.</dd>
 <dt>{{domxref("HTMLFormElement.autocomplete")}}</dt>
 <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("autocomplete", "form") }} HTML attribute, indicating whether the controls in this form can have their values automatically populated by the browser.</dd>
 <dt>{{domxref("HTMLFormElement.noValidate")}}</dt>
 <dd>A {{jsxref("Boolean")}} reflecting the value of the form's  {{ htmlattrxref("novalidate", "form") }} HTML attribute, indicating whether the form should not be validated.</dd>
</dl>

<p>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 <code>action</code> will have its <code>action</code> property return that input instead of the form's {{ htmlattrxref("action", "form") }} HTML attribute).</p>

<h2 id="Methods">Methods</h2>

<p><em>This interface also inherits methods from its parent, {{domxref("HTMLElement")}}.</em></p>

<dl>
 <dt>{{domxref("HTMLFormElement.checkValidity", "checkValidity()")}}</dt>
 <dd>Returns <code>true</code> if the element's child controls are subject to <a href="/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation">constraint validation</a> and satisfy those contraints; returns <code>false</code> 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 <code>false</code>.</dd>
 <dt>{{domxref("HTMLFormElement.reportValidity", "reportValidity()")}}</dt>
 <dd>Returns <code>true</code> if the element's child controls satisfy their <a href="/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation">validation constraints</a>. When <code>false</code> is returned, cancelable {{Event("invalid")}} events are fired for each invalid child and validation problems are reported to the user.</dd>
 <dt>{{domxref("HTMLFormElement.requestSubmit", "requestSubmit()")}}</dt>
 <dd>Requests that the form be submitted using the specified submit button and its corresponding configuration.</dd>
 <dt>{{domxref("HTMLFormElement.reset", "reset()")}}</dt>
 <dd>Resets the form to its initial state.</dd>
 <dt>{{domxref("HTMLFormElement.submit", "submit()")}}</dt>
 <dd>Submits the form to the server.</dd>
</dl>

<h3 id="Deprecated_methods">Deprecated methods</h3>

<dl>
 <dt>{{domxref("HTMLFormElement.requestAutocomplete()")}} {{deprecated_inline}}</dt>
 <dd>Triggers a native browser interface to assist the user in completing the fields which have an <a href="https://html.spec.whatwg.org/#autofill-field-name">autofill field name</a> value that is not <code>off</code> or <code>on</code>. 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.</dd>
</dl>

<h2 id="Events">Events</h2>

<p>Listen to these events using <code>addEventListener()</code> or by assigning an event listener to the <code>on<em>eventname</em></code> property of this interface.</p>

<dl>
 <dt><code><a href="/en-US/docs/Web/API/HTMLFormElement/formdata_event">formdata</a></code></dt>
 <dd><span style="display: none;"> </span>The <code>formdata</code> event fires after the entry list representing the form's data is constructed.<br>
 Also available via the <code><a href="/en-US/docs/Web/API/GlobalEventHandlers/onformdata">onformdata</a></code> property.</dd>
 <dt><code><a href="/en-US/docs/Web/API/HTMLFormElement/reset_event">reset</a></code></dt>
 <dd><span style="display: none;"> </span>The <code>reset</code> event fires when a form is reset.<br>
 Also available via the <code><a href="/en-US/docs/Web/API/GlobalEventHandlers/onreset">onreset</a></code> property.</dd>
 <dt><code><a href="/en-US/docs/Web/API/HTMLFormElement/submit_event">submit</a></code></dt>
 <dd>The <code>submit</code> event fires when a form is submitted.<br>
 Also available via the <code><a href="/en-US/docs/Web/API/GlobalEventHandlers/onsubmit">onsubmit</a></code> property.</dd>
</dl>

<h2 id="Usage_notes">Usage notes</h2>

<h3 id="Obtaining_a_form_element_object">Obtaining a form element object</h3>

<p>To obtain an <code>HTMLFormElement</code> object, you can use a <a href="/en-US/docs/Web/CSS/CSS_Selectors">CSS selector</a> 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.</p>

<p>{{domxref("Document.forms")}} returns an array of <code>HTMLFormElement</code> objects listing each of the forms on the page. You can then use any of the following syntaxes to get an individual form:</p>

<dl>
 <dt><code>document.forms[<em>index</em>]</code></dt>
 <dd>Returns the form at the specified <code>index</code> into the array of forms.</dd>
 <dt><code>document.forms[<em>id</em>]</code></dt>
 <dd>Returns the form whose ID is <code>id</code>.</dd>
 <dt><code>document.forms[<em>name</em>]</code></dt>
 <dd>Returns the form whose {{domxref("Element.name", "name")}} attribute's value is <code>name</code>.</dd>
</dl>

<h3 id="Accessing_the_forms_elements">Accessing the form's elements</h3>

<p>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 <code>&lt;form&gt;</code> and those which are made members of the form using their <code>form</code> attributes.</p>

<p>You can also get the form's element by using its <code>name</code> attribute as a key of the <code>form</code>, but using <code>elements</code> is a better approach — it contains only the form's elements, and it cannot be mixed with other attributes of the <code>form</code>.</p>

<h3 id="Elements_that_are_considered_form_controls">Elements that are considered form controls</h3>

<p>The elements which are included by <code>HTMLFormElement.elements</code> and <code>HTMLFormElement.length</code> are:</p>

<ul>
 <li>{{HTMLElement("button")}}</li>
 <li>{{HTMLElement("fieldset")}}</li>
 <li>{{HTMLElement("input")}} (with the exception that any whose {{htmlattrxref("type", "input")}} is <code>"image"</code> are omitted for historical reasons)</li>
 <li>{{HTMLElement("object")}}</li>
 <li>{{HTMLElement("output")}}</li>
 <li>{{HTMLElement("select")}}</li>
 <li>{{HTMLElement("textarea")}}</li>
</ul>

<p>No other elements are included in the list returned by <code>elements</code>, which makes it an excellent way to get at the elements most important when processing forms.</p>

<h2 id="Examples">Examples</h2>

<p>Creating a new form element, modifying its attributes, then submitting it:</p>

<pre class="brush: js">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
</pre>

<p>Extract information from a form element and set some of its attributes:</p>

<pre class="brush: html">&lt;form name="formA" action="/cgi-bin/test" method="post"&gt;
 &lt;p&gt;Press "Info" for form details, or "Set" to change those details.&lt;/p&gt;
 &lt;p&gt;
  &lt;button type="button" onclick="getFormInfo();"&gt;Info&lt;/button&gt;
  &lt;button type="button" onclick="setFormInfo(this.form);"&gt;Set&lt;/button&gt;
  &lt;button type="reset"&gt;Reset&lt;/button&gt;
 &lt;/p&gt;

 &lt;textarea id="form-info" rows="15" cols="20"&gt;&lt;/textarea&gt;
&lt;/form&gt;

&lt;script&gt;
  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 &lt;textarea&gt; 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";
  }
&lt;/script&gt;
</pre>

<p>Submit a form into a new window:</p>

<pre class="brush: html">&lt;!doctype html&gt;
&lt;html&gt;
&lt;head&gt;
&lt;meta charset="utf-8"&gt;
&lt;title&gt;Example new-window form submission&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;

&lt;form action="test.php" target="_blank"&gt;
  &lt;p&gt;&lt;label&gt;First name: &lt;input type="text" name="firstname"&gt;&lt;/label&gt;&lt;/p&gt;
  &lt;p&gt;&lt;label&gt;Last name: &lt;input type="text" name="lastname"&gt;&lt;/label&gt;&lt;/p&gt;
  &lt;p&gt;&lt;label&gt;&lt;input type="password" name="pwd"&gt;&lt;/label&gt;&lt;/p&gt;

  &lt;fieldset&gt;
   &lt;legend&gt;Pet preference&lt;/legend&gt;
    &lt;p&gt;&lt;label&gt;&lt;input type="radio" name="pet" value="cat"&gt; Cat&lt;/label&gt;&lt;/p&gt;
    &lt;p&gt;&lt;label&gt;&lt;input type="radio" name="pet" value="dog"&gt; Dog&lt;/label&gt;&lt;/p&gt;
  &lt;/fieldset&gt;

  &lt;fieldset&gt;
    &lt;legend&gt;Owned vehicles&lt;/legend&gt;

    &lt;p&gt;&lt;label&gt;&lt;input type="checkbox" name="vehicle" value="Bike"&gt;I have a bike&lt;/label&gt;&lt;/p&gt;
    &lt;p&gt;&lt;label&gt;&lt;input type="checkbox" name="vehicle" value="Car"&gt;I have a car&lt;/label&gt;&lt;/p&gt;
  &lt;/fieldset&gt;

  &lt;p&gt;&lt;button&gt;Submit&lt;/button&gt;&lt;/p&gt;
&lt;/form&gt;

&lt;/body&gt;
&lt;/html&gt;</pre>

<h3 id="Submitting_forms_and_uploading_files_using_XMLHttpRequest">Submitting forms and uploading files using <code>XMLHttpRequest</code></h3>

<p>If you want to know how to serialize and submit a form using the {{domxref("XMLHttpRequest")}} API, please read <a href="/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest#Submitting_forms_and_uploading_files">this paragraph</a>.</p>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('HTML WHATWG', "#htmlformelement", "HTMLFormElement")}}</td>
   <td>{{Spec2('HTML WHATWG')}}</td>
   <td>The following method has been added: <code>requestAutocomplete()</code>.</td>
  </tr>
  <tr>
   <td>{{SpecName('HTML5 W3C', "sec-forms.html#htmlformelement", "HTMLFormElement")}}</td>
   <td>{{Spec2('HTML5 W3C')}}</td>
   <td>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: <code>checkValidity()</code>. The following properties have been added: <code>autocomplete</code>, <code>noValidate</code>, and <code>encoding</code>.</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>



<p>{{Compat("api.HTMLFormElement")}}</p>

<h2 id="See_also">See also</h2>

<ul>
 <li>The HTML element implementing this interface: {{ HTMLElement("form") }}.</li>
</ul>