Referencing Forms and Form Elements

This page demonstrates and describes various approaches to obtaining references to forms and form elements in JavaScript. Both traditional and modern methods are covered.

Modern Referencing Methods

The getElementById and getElementsByName methods can be used to obtain references to forms and form elements. The getElementById method returns the single matching element with the specified ID; getElementsByName returns an array-like list of elements[1] that match the name specified.

An example demonstrates with two radio buttons that have the name gender:

<input type="radio" name="gender" value="male" /> male 
<input type="radio" name="gender" value="female" /> female

The following demonstrates obtaining references to them using getElementsByName:

var gender = document.getElementsByName('gender');
alert( gender.length ); // 2
// view the value of the first element with name gender
alert( gender[0].value ); // male

The getElementsByName method is defined on document, so it could not be used to find elements with a particular name in a specific form. The getElementsByName method is seldom used, yet it does have broad browser support.

The getElementsByTagName, querySelectorAll, and other methods discussed in Obtaining Element References in JavaScript can also be used to reference forms and form elements.

Names vs. IDs for Forms and Form Elements

There would be no particular need to apply a name attribute to a form. The form name attribute is not valid in XHTML. Using an ID rather than a name to identify and obtain a reference to a form is generally preferable.

On the other hand, name attributes on form elements are valid and necessary for successful submission to server side code. If you are associating a label element with a form element using a for attribute, the form element needs an ID:

<label for="firstName">First Name: </label>
<input type="text" name="firstName" id="firstName" />

Thus, form elements will typically include a name attribute and may also include an ID attribute if needed. Keep in mind that IDs need to be unique in the document, while the same name may be applied to multiple form elements. This is typical with sets of radio inputs and often checkboxes as well.

Using Forms and Elements Collections

All the forms in a document are contained in the document.forms HTMLCollection. All the elements of any given form are contained in an elements property of that form which is also an HTMLCollection.

The forms and elements collections have been standardized as part of the W3C DOM for backwards compatibility. You can expect them to be broadly supported both in older browsers and future browsers.[2]

If you have a form with the id or name attribute specified as myForm, you could obtain a reference to it through the document.forms collection as follows:

var formRef = document.forms.myForm;
// or
var formRef = document.forms['myForm'];

If you have a form element with a name or id firstName in the form with name or id myForm you could obtain a reference to it through the elements collection as follows:

var fName = document.forms.myForm.elements.firstName;
// or
var fName = document.forms['myForm'].elements['firstName'];
// or, using formRef as obtained above:
var fName = formRef.elements.firstName;
// or
var fName = formRef.elements['firstName'];

If more than one element has the specified name, as would be typical with radio buttons and perhaps checkboxes, an HTML collection is returned:

// reference to radio buttons with name gender
var gender = document.forms['demoForm'].elements['gender'];
alert( gender[0].value ); // male
alert( gender.length ); // 2

Numerical Indexes with Forms and Elements Collections

Members of HTML collections can be referenced using numerical indexes just as you can do with arrays. For example, the following can be used to reference the first element in the first form in the document:

var el = document.forms[0].elements[0];

This form of referencing is error prone and hard to maintain because changes in the forms and form elements in your document would necessitate changes in your JavaScript as well.

Referencing Approaches to Avoid

A form with a name attribute can be referenced as a property of the document. For example, a form with the name (but not id) myForm can be referenced as follows:

// works with form name but not id
var formRef = document.myForm;

The same approach works for form elements as well. A form element in the form named myForm with the name or id firstName could be referenced as follows:

var fName = document.myForm.firstName;
// or, using formRef as obtained above:
var fName = formRef.firstName;

This approach to referencing is nonstandard and may not be supported in future browsers. These methods can be unreliable for other reasons as well. They could conflict with other properties defined on the document or form object and should be avoided.

Back to top

  1. This array-like list of element references is called an HTMLCollection. It lists the elements in document order. Its members can be accessed by index, name, or id. Find more information in the description of the very similar node list. ^
  2. These methods of referencing don't appear to work for input type image. To obtain references to input type image, use the newer methods such as getElementById or getElementsByName. ^