Revision 1018190 of HTMLCollection

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

<p>The <strong><code>HTMLCollection</code></strong> interface represents a generic collection (array-like object similar to <a href="/en-US/docs/Web/JavaScript/Reference/Functions/arguments">arguments</a>) 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="Specifications" name="Specifications">Specifications</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('DOM WHATWG', '#htmlcollection', 'HTMLCollection')}}</td>
   <td>{{ Spec2('DOM WHATWG') }}</td>
   <td>&nbsp;</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM4', '#htmlcollection', 'HTMLCollection')}}</td>
   <td>{{ Spec2('DOM4') }}</td>
   <td>&nbsp;</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM2 HTML', 'html.html#ID-75708506', 'HTMLCollection')}}</td>
   <td>{{ Spec2('DOM2 HTML') }}</td>
   <td>&nbsp;</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM1', 'level-one-html.html#ID-75708506', 'HTMLCollection')}}</td>
   <td>{{ Spec2('DOM1') }}</td>
   <td>Initial definition.</td>
  </tr>
 </tbody>
</table>


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

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