Revision 786884 of HTMLCollection

<p>{{APIRef("HTML DOM")}}</p>

<p>The <strong><code>HTMLCollection</code></strong> interface represents a generic collection (array-like object) of elements (in document order) and offers methods and properties for selecting from the list.</p>

<div class="note"><strong>Note:</strong> This interface is called <code>HTMLCollection</code> for historical reasons (before DOM4, collections implementing this interface could only have HTML elements as their items).</div>

<p>An <code>HTMLCollection</code> in the HTML DOM is live; it is automatically updated when the underlying document is changed.</p>

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

<dl>
 <dt>{{domxref("HTMLCollection.length")}} {{readonlyInline}}</dt>
 <dd>Returns the number of items in the collection.</dd>
</dl>

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

<dl>
 <dt>{{domxref("HTMLCollection.item()")}}</dt>
 <dd>Returns the specific node at the given zero-based <code>index</code> into the list. Returns <code>null</code> if the <code>index</code> is out of range.</dd>
 <dt>{{domxref("HTMLCollection.namedItem()")}}</dt>
 <dd>Returns the specific node whose ID or, as a fallback, name matches the string specified by <code>name</code>. Matching by name is only done as a last resort, only in HTML, and only if the referenced element supports the <code>name</code> attribute. Returns <code>null</code> if no node exists by the given name.</dd>
</dl>

<h2 id="Usage_in_JavaScript">Usage in JavaScript</h2>

<p><code>HTMLCollection also</code> exposes its members directly as properties by both name and index. HTML&nbsp;IDs may contain&nbsp;: and . as valid characters, which would necessitate using bracket notation for property access. Currently HTMLCollections does not recognize purely numeric IDs, which would cause conflict with the array-style access,&nbsp;though HTML5 does permit&nbsp;these.</p>

<p>For example, assuming there is one <code>&lt;form&gt;</code> element in the document and its <code>id</code> is <code>"myForm"</code>:</p>

<pre class="brush:js">
var elem1, elem2;

// document.forms is an HTMLCollection

elem1 = document.forms[0];
elem2 = document.forms.item(0);

alert(elem1 === elem2); // shows: "true"

elem1 = document.forms.myForm;
elem2 = document.forms.namedItem("myForm");

alert(elem1 === elem2); // shows: "true"

elem1 = document.forms["named.item.with.periods"];</pre>

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

<p>Different browsers behave differently when there are more than one elements matching the string used as an index (or <code>namedItem</code>'s argument). Firefox 8 behaves as specified in DOM 2 and DOM4, returning the first matching element. WebKit browsers and Internet Explorer in this case return another <code>HTMLCollection</code> and Opera returns a {{domxref("NodeList")}} of all matching elements.</p>

<h2 id="Specification">Specification</h2>

<ul>
 <li><a href="https://www.w3.org/TR/DOM-Level-2-HTML/html.html#ID-75708506" title="https://www.w3.org/TR/DOM-Level-2-HTML/html.html#ID-75708506">DOM Level 2 HTML, Section 1.4, Miscellaneous Object Definitions</a></li>
 <li><a href="https://www.w3.org/TR/domcore/#interface-htmlcollection" title="https://www.w3.org/TR/domcore/#interface-htmlcollection">DOM4: HTMLCollection</a></li>
</ul>

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

<ul>
 <li>{{domxref("NodeList")}}</li>
 <li>{{domxref("HTMLFormControlsCollection")}}, {{domxref("HTMLOptionsCollection")}}</li>
</ul>