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

Instance properties

This interface also inherits properties from its parent,HTMLElement.

HTMLFormElement.acceptCharset

A string reflecting the value of the form'saccept-charset HTML attribute.

HTMLFormElement.action

A string reflecting the value of the form'saction HTML attribute, containing the URI of a program that processes the information submitted by the form.

HTMLFormElement.autocomplete

A string 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.encoding orHTMLFormElement.enctype

A string 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.elementsRead only

AHTMLFormControlsCollection holding all form controls belonging to this form element.

HTMLFormElement.lengthRead only

Along reflecting the number of controls in the form.

HTMLFormElement.name

A string reflecting the value of the form'sname HTML attribute, containing the name of the form.

HTMLFormElement.noValidate

A boolean value reflecting the value of the form'snovalidate HTML attribute, indicating whether the form should not be validated.

HTMLFormElement.method

A string 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.rel

A string reflecting the value of the form'srel HTML attribute, which represents what kinds of links the form creates as a space-separated list of enumerated values.

HTMLFormElement.relListRead only

ADOMTokenList that reflects therel HTML attribute, as a list of tokens.

HTMLFormElement.target

A string reflecting the value of the form'starget HTML attribute, indicating where to display the results received from submitting the form.

Named inputs are added to their owner form instance as properties, and can overwrite native properties if they share the same name (e.g., a form with an input namedaction will have itsaction property return that input instead of the form'saction HTML attribute).

Instance methods

This interface also inherits methods from its parent,HTMLElement.

checkValidity()

Returnstrue if the element's child controls are subject toconstraint validation and satisfy those constraints; 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.

reportValidity()

Returnstrue if the element's child controls satisfy theirvalidation constraints. Whenfalse is returned, cancelableinvalid events are fired for each invalid child and validation problems are reported to the user.

requestSubmit()

Requests that the form be submitted using the specified submit button and its corresponding configuration.

reset()

Resets the form to its initial state.

submit()

Submits the form to the server.

Events

Listen to these events usingaddEventListener(), or by assigning an event listener to theoneventname property of this interface.

formdata

Theformdata event fires after the entry list representing the form's data is constructed.

reset

Thereset event fires when a form is reset.

submit

Thesubmit event fires when a form is submitted.

Usage notes

Obtaining a form element object

To obtain anHTMLFormElement object, you can use aCSS selector withquerySelector(), or you can get a list of all of the forms in the document using itsforms property.

Document.forms returns an array ofHTMLFormElement 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 specifiedindex into the array of forms.

document.forms[id]

Returns the form whose ID isid.

document.forms[name]

Returns the form whosename 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'selements property. This returns anHTMLFormControlsCollection 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 theirform attributes.

You can also get the form's element by using itsname attribute as a key of theform, but usingelements is a better approach—it containsonly the form's elements, and it cannot be mixed with other attributes of theform.

Issues with Naming Elements

Some names will interfere with JavaScript access to the form's properties and elements.

For example:

• <input name="id"> will take precedence over<form>. This means thatform.id will not refer to the form's id, but to the element whose name is"id". This will be the case with any other form properties, such as<input name="action"> or<input name="post">.
• <input name="elements"> will render the form'selements collection inaccessible. The referenceform.elements will now refer to the individual element.

To avoid such problems with element names:

• Always use theelements collection to avoid ambiguity between an element name and a form property.
• Never use"elements" as an element name.

If you are not using JavaScript, this will not cause a problem.

Elements that are considered form controls

The elements included byHTMLFormElement.elements andHTMLFormElement.length are the following:

• <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 byelements, which makes it an excellent way to get at the most important elements when processing forms.

Examples

Creating a new form element, modifying its attributes, then submitting it:

const f = document.createElement("form"); // Create a formdocument.body.appendChild(f); // Add it to the document bodyf.action = "/cgi-bin/some.cgi"; // Add action and method attributesf.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">Info</button>    <button type="button">Set</button>    <button type="reset">Reset</button>  </p>  <textarea rows="15" cols="20"></textarea></form>

document.getElementById("info").addEventListener("click", () => {  // Get a reference to the form via its name  const f = document.forms["formA"];  // The form properties we're interested in  const 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  const info = properties    .map((property) => `${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});document.getElementById("set-info").addEventListener("click", (e) => {  // Get a reference to the form via the event target  // e.target is the button, and .form is the form it belongs to  const f = e.target.form;  // Argument should be a form element reference.  f.action = "a-different-url.cgi";  f.name = "a-different-name";});

Submit a<form> into a new window:

<form action="test.php">  <p>    <label>First name: <input type="text" name="first-name" /></label>  </p>  <p>    <label>Last name: <input type="text" name="last-name" /></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>

Specifications

Browser compatibility

See also

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