HTMLCollection

BaselineWidely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

TheHTMLCollection interface represents a generic collection (array-like object similar toarguments) of elements (in document order) and offers methods and properties for selecting from the list.

AnHTMLCollection in the HTML DOM is live; it is automatically updated when the underlying document is changed. For this reason it is a good idea to make a copy (e.g., usingArray.from) to iterate over if adding, moving, or removing nodes.

This interface is calledHTMLCollection for historical reasons, because before the modern DOM, collections implementing this interface could only have HTML elements as their items.

This interface was anattempt to create an unmodifiable list and only continues to be supported to not break code that's already using it. Modern APIs represent list structures using types based on JavaScriptarrays, thus making many array methods available, and at the same time imposing additional semantics on their usage (such as making their items read-only).

These historical reasons do not mean that you as a developer should avoidHTMLCollection. You don't createHTMLCollection objects yourself, but you get them from APIs such asDocument.getElementsByClassName(), and these APIs are not deprecated. However, be careful of the semantic differences from a real array.

Instance properties

HTMLCollection.lengthRead only: Returns the number of items in the collection.

Instance methods

HTMLCollection.item()

Returns the specific element at the given zero-basedindex into the list. Returnsnull if theindex is out of range.

An alternative to accessingcollection[i] (which instead returnsundefined wheni is out-of-bounds). This is mostly useful for non-JavaScript DOM implementations.

HTMLCollection.namedItem()

Returns the specific node whose ID or, as a fallback, name matches the string specified byname. Matching by name is only done as a last resort, only in HTML, and only if the referenced element supports thename attribute. Returnsnull if no node exists by the given name.

An alternative to accessingcollection[name] (which instead returnsundefined whenname does not exist). This is mostly useful for non-JavaScript DOM implementations.

Usage in JavaScript

HTMLCollection also exposes its members as properties by name and index. HTML IDs may contain: and. as valid characters, which would necessitate using bracket notation for property access. Currently, anHTMLCollection object does not recognize purely numeric IDs, which would cause conflict with the array-style access, though HTML does permit these.

For example, assuming there is one<form> element in the document and itsid ismyForm:

let elem1, elem2;// document.forms is an HTMLCollectionelem1 = 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"];