docs.rodeo

MDN Web Docs mirror

HTMLFormElement

{{APIRef("HTML DOM")}} 

The 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}} 

Instance properties

This interface also inherits properties from its parent, {{domxref("HTMLElement")}} .

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 named action will have its action property return that input instead of the form’s action HTML attribute).

Instance methods

This interface also inherits methods from its parent, {{domxref("HTMLElement")}} .

Events

Listen to these events using addEventListener(), or by assigning an event listener to the oneventname property of this interface.

Usage notes

Obtaining a form element object

To obtain an HTMLFormElement object, you can use a CSS selector with {{domxref("Document.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:

Accessing the form’s elements

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.

Issues with Naming Elements

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

For example:

To avoid such problems with element names:

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

Elements that are considered form controls

The elements included by HTMLFormElement.elements and HTMLFormElement.length are the following:

No other elements are included in the list returned by elements, 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 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
    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
  }

  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 lang="en-US">
  <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="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>
  </body>
</html>

Specifications

{{Specifications}} 

Browser compatibility

{{Compat}} 

See also

In this article

View on MDN