The HTMLFormElement
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.
The HTMLFormElement
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.
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.length
Read only
A long
reflecting the number of controls in the form.
HTMLFormElement.name
A string reflecting the value of the form's name
HTML attribute, containing the name of the form.
HTMLFormElement.method
A string 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 string reflecting the value of the form's target
HTML attribute, indicating where to display the results received from submitting the form.
HTMLFormElement.action
A string 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 string 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 string reflecting the value of the form's accept-charset
HTML attribute, representing the character encoding that the server accepts.
HTMLFormElement.autocomplete
A string 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 value 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 (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).
This interface also inherits methods from its parent, HTMLElement
.
checkValidity()
Returns true
if the element's child controls are subject to constraint validation and satisfy those constraints; 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
.
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.
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.
HTMLFormElement.requestAutocomplete()
Deprecated
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.
Listen to these events using addEventListener()
, or by assigning an event listener to the oneventname
property of this interface.
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
.
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.
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
.
Some names will interfere with JavaScript access to the form's properties and elements.
For example:
<input name="id">
will take precedence over <form id="…">
. This means that form.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's elements
collection inaccessible. The reference form.elements
will now refer to the individual element.To avoid such problems with element names:
elements
collection to avoid ambiguity between an element name and a form property.elements
" as an element name.If you are not using JavaScript, this will not cause a problem.
The elements included by HTMLFormElement.elements
and HTMLFormElement.length
are the following:
<button>
<fieldset>
<input>
(with the exception that any whose type
is "image"
are omitted for historical reasons)<object>
<output>
<select>
<textarea>
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:
js
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:
html
<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:
html
<!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="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>
Specification |
---|
HTML Standard # htmlformelement |
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
HTMLFormElement |
1 | 12 | 1 | 5.5 | 8 | 3 | 4.4 | 18 | 4 | 10.1 | 1 | 1.0 |
acceptCharset |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
action |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
autocomplete |
14 | 12 | 4 | 10 | 15 | 6 | 4.4 | 18 | 4 | 14 | 6 | 1.0 |
checkValidity |
4 | 12 | 4 | 10 | ≤12.1 | 5 | ≤37 | 18 | 4 | ≤12.1 | 4 | 1.0 |
elements |
1 | 12 | 1 | 5.5 | 8 | 3 | 4.4 | 18 | 4 | 10.1 | 1 | 1.0 |
encoding |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
enctype |
1 | 12 | 1 | 6 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
formdata_event |
77 | 79 | 72 | No | 64 | 15 | 77 | 77 | 79 | 55 | 15 | 12.0 |
length |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
method |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
name |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
noValidate |
4 | 12 | 4 | 10 | ≤12.1 | 5 | ≤37 | 18 | 4 | ≤12.1 | 4 | 1.0 |
rel |
108 | 108 | 111 | No | 94 | 15.4 | 108 | 108 | 111 | 73 | 15.4 | 21.0 |
relList |
108 | 108 | 111 | No | 94 | 15.4 | 108 | 108 | 111 | 73 | 15.4 | 21.0 |
reportValidity |
40 | 17 | 49 | No | 27 | 10.1 | 40 | 40 | 49 | 27 | 10.3 | 4.0 |
requestSubmit |
76 | 79 | 75 | No | 63 | 16 | 76 | 76 | 79 | 54 | 16 | 12.0 |
reset |
1 | 12 | 1 | 5.5 | 8 | 3 | 4.4 | 18 | 4 | 10.1 | 1 | 1.0 |
reset_event |
1 | 12 | 6 | 9 | ≤12.1 | 3 | ≤37 | 18 | 6 | ≤12.1 | 1 | 1.0 |
submit |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
submit_event |
1 | 12 | 1 | 9 | 8 | 3 | 4.4 | 18 | 4 | 10.1 | 1 | 1.0 |
target |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
<form>
.
© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement